@pixelume/sdk 0.4.0 → 0.6.0

package/dist/modules/auth/AuthModule.js

@@ -3,6 +3,12 @@ import { PixelumeAuthError, PixelumeConfigError, isPixelumeError, } from '../../
 import { SessionManager, browserResumeSource, } from './SessionManager.js';
 const AUTHORIZATION_REQUEST_TTL_MS = 10 * 60_000;
 const CALLBACK_PARAMETERS = ['code', 'state', 'error', 'error_description'];
+/** `prompt=none` answers meaning "the central session cannot authorize without a screen". */
+const SESSION_ENDED_ERRORS = new Set([
+    'login_required',
+    'consent_required',
+    'interaction_required',
+]);
 export class AuthModule {
     #http;
     #config;
@@ -13,16 +19,22 @@ export class AuthModule {
     #loginPromise = null;
     #playerPromise = null;
     #logoutPromise = null;
+    /** True while a callback of a silent attempt is being completed. */
+    #completingRestore = false;
+    #resume;
+    #stopRestoreWatch = null;
     constructor(http, config) {
         this.#http = http;
         this.#config = config;
         const browser = config.browser;
+        this.#resume =
+            browser !== undefined && typeof browser.subscribeResume === 'function'
+                ? (onResume) => browser.subscribeResume?.(onResume) ?? (() => undefined)
+                : browserResumeSource();
         this.#session = new SessionManager({
             http,
             clientId: () => this.#requireClientId(),
-            resume: browser !== undefined && typeof browser.subscribeResume === 'function'
-                ? (onResume) => browser.subscribeResume?.(onResume) ?? (() => undefined)
-                : browserResumeSource(),
+            resume: this.#resume,
             onEnded: (error) => {
                 this.#setState(anonymous('expired', error));
             },
@@ -46,6 +58,8 @@ export class AuthModule {
     }
     /** @internal Releases timers/listeners and drops credentials from memory (no revocation). */
     dispose() {
+        this.#stopRestoreWatch?.();
+        this.#stopRestoreWatch = null;
         this.#session.dispose();
         this.#listeners.clear();
     }
@@ -62,7 +76,7 @@ export class AuthModule {
         if (scope !== 'profile' && scope !== 'profile saves') {
             return Promise.reject(new PixelumeConfigError('Pixelume Auth scope must be "profile" or "profile saves"'));
         }
-        this.#loginPromise ??= this.#doLogin(scope).finally(() => {
+        this.#loginPromise ??= this.#doLogin(scope, false).finally(() => {
             this.#loginPromise = null;
         });
         return this.#loginPromise;
@@ -88,40 +102,92 @@ export class AuthModule {
             if (callback !== null) {
                 await this.#handleCallback(browser, callback);
             }
-            else if (this.#config.restoreSession) {
-                const scope = this.#readSessionHint(browser.sessionStorage);
-                if (scope === null) {
-                    this.#setState(anonymous('visitor'));
+            else {
+                const persistent = this.#persistentStorage(browser);
+                if (this.#config.crossSessionRestore !== null && persistent !== null) {
+                    await this.#restoreAcrossSessions(browser, persistent, this.#config.crossSessionRestore);
                 }
                 else {
-                    this.#removeSessionHint(browser.sessionStorage);
-                    await this.login({ scope });
+                    // The feature was turned off: do not leave a stale hint behind.
+                    if (persistent !== null)
+                        this.#removePersistentHint(persistent);
+                    await this.#restoreSameTab(browser);
                 }
             }
-            else {
-                this.#setState(anonymous('visitor'));
-            }
         }
         catch (error) {
             const failure = isPixelumeError(error)
                 ? error
                 : new PixelumeAuthError('browser_unavailable', { cause: error });
-            this.#setState(anonymous('error', failure));
+            const offline = this.#completingRestore && (failure.kind === 'network' || failure.kind === 'timeout');
+            this.#setState(anonymous(offline ? 'offline' : 'error', failure));
+        }
+        finally {
+            this.#completingRestore = false;
         }
         return this.#state;
     }
-    async #doLogin(scope) {
+    /** Behaviour without `restoreAcrossSessions` (unchanged since 0.2): same-tab reload only. */
+    async #restoreSameTab(browser) {
+        const scope = this.#config.restoreSession
+            ? this.#readSessionHint(browser.sessionStorage)
+            : null;
+        if (scope === null) {
+            this.#setState(anonymous('visitor'));
+            return;
+        }
+        this.#removeSessionHint(browser.sessionStorage);
+        await this.login({ scope });
+    }
+    /**
+     * At most one silent (`prompt=none`) attempt per start, driven by the tab hint (reload) or the
+     * persistent hint (new tab, reopened browser). A per-tab marker stops a second attempt while a
+     * previous one did not come back (navigation error, back button), so it can never loop.
+     */
+    async #restoreAcrossSessions(browser, persistent, options) {
+        const tabScope = this.#config.restoreSession
+            ? this.#readSessionHint(browser.sessionStorage)
+            : null;
+        const hint = this.#readPersistentHint(persistent, options.maxAgeMs);
+        const remembered = tabScope ?? hint?.scope ?? null;
+        if (remembered === null) {
+            this.#setState(anonymous('visitor'));
+            return;
+        }
+        if (this.#recentRestoreAttempt(browser.sessionStorage)) {
+            this.#setState(anonymous('visitor'));
+            return;
+        }
+        if (!isOnline(browser)) {
+            this.#setState(anonymous('offline'));
+            return;
+        }
+        // Never ask silently for more than both the game and the previous grant allow.
+        const scope = remembered === 'profile saves' && this.#config.scope === 'profile saves'
+            ? 'profile saves'
+            : 'profile';
+        this.#removeSessionHint(browser.sessionStorage);
+        await this.#doLogin(scope, true);
+    }
+    async #doLogin(scope, silent) {
         const clientId = this.#requireClientId();
         const redirectUri = this.#requireRedirectUri();
         const browser = this.#browser();
         let pending = this.#readPending(browser.sessionStorage);
-        if (pending === null || pending.redirectUri !== redirectUri || this.#isExpired(pending)) {
+        if (silent ||
+            pending === null ||
+            pending.redirectUri !== redirectUri ||
+            pending.silent === true ||
+            this.#isExpired(pending)) {
+            const returnTo = silent ? sameOriginPath(browser.currentUrl(), redirectUri) : null;
             pending = {
                 version: 1,
                 state: randomBase64Url(browser.crypto),
                 verifier: randomBase64Url(browser.crypto),
                 redirectUri,
                 createdAt: Date.now(),
+                ...(silent ? { silent: true, scope } : {}),
+                ...(returnTo === null ? {} : { returnTo }),
             };
             this.#writePending(browser.sessionStorage, pending);
         }
@@ -135,8 +201,13 @@ export class AuthModule {
             code_challenge: challenge,
             code_challenge_method: 'S256',
             scope,
+            ...(silent ? { prompt: 'none' } : {}),
         }).toString();
-        this.#setState(Object.freeze({ status: 'redirecting', player: null }));
+        if (silent)
+            this.#writeRestoreAttempt(browser.sessionStorage);
+        this.#setState(Object.freeze(silent
+            ? { status: 'redirecting', player: null, restoring: true }
+            : { status: 'redirecting', player: null }));
         try {
             browser.navigate(authorization.toString());
         }
@@ -144,11 +215,36 @@ export class AuthModule {
             this.#removePending(browser.sessionStorage);
             throw new PixelumeAuthError('browser_unavailable', { cause });
         }
+        if (silent)
+            this.#watchInterruptedRestore();
+    }
+    /**
+     * If the page comes back without leaving (back/forward cache, navigation error then "back"),
+     * the silent attempt is over: become a visitor instead of staying in `redirecting`. The per-tab
+     * marker stays, so the next start does not try again right away.
+     */
+    #watchInterruptedRestore() {
+        this.#stopRestoreWatch?.();
+        if (this.#resume === null)
+            return;
+        const stop = this.#resume(() => {
+            const current = this.#state;
+            if (current.status === 'redirecting' && current.restoring === true) {
+                this.#setState(anonymous('visitor'));
+            }
+            stop();
+            if (this.#stopRestoreWatch === stop)
+                this.#stopRestoreWatch = null;
+        });
+        this.#stopRestoreWatch = stop;
     }
     async #handleCallback(browser, callback) {
         const pending = this.#readPending(browser.sessionStorage);
         this.#removePending(browser.sessionStorage);
-        this.#cleanCallback(browser, callback.url);
+        this.#removeRestoreAttempt(browser.sessionStorage);
+        const silent = pending?.silent === true && !this.#isExpired(pending);
+        this.#cleanCallback(browser, callback.url, silent ? (pending.returnTo ?? null) : null);
+        this.#completingRestore = silent;
         if (callback.invalid)
             throw new PixelumeAuthError('invalid_callback');
         if (pending === null || this.#isExpired(pending)) {
@@ -166,6 +262,27 @@ export class AuthModule {
         }
         if (callback.error !== null) {
             this.#removeSessionHint(browser.sessionStorage);
+            const persistent = this.#persistentStorage(browser);
+            if (silent) {
+                this.#completingRestore = false;
+                if (SESSION_ENDED_ERRORS.has(callback.error)) {
+                    if (persistent !== null)
+                        this.#removePersistentHint(persistent);
+                    this.#setState(anonymous('session_ended'));
+                    return;
+                }
+                if (callback.error === 'invalid_scope' && pending.scope === 'profile saves') {
+                    // The game no longer allows `saves`: the next start tries `profile` only.
+                    if (persistent !== null)
+                        this.#downgradePersistentHint(persistent);
+                }
+                else if (persistent !== null) {
+                    this.#removePersistentHint(persistent);
+                }
+                throw new PixelumeAuthError('restore_rejected');
+            }
+            if (persistent !== null)
+                this.#removePersistentHint(persistent);
             if (callback.error === 'access_denied') {
                 this.#setState(anonymous('cancelled'));
                 return;
@@ -174,7 +291,9 @@ export class AuthModule {
         }
         if (callback.code === null)
             throw new PixelumeAuthError('invalid_callback');
-        this.#setState(Object.freeze({ status: 'exchanging', player: null }));
+        this.#setState(Object.freeze(silent
+            ? { status: 'exchanging', player: null, restoring: true }
+            : { status: 'exchanging', player: null }));
         const response = await this.#http.request({
             method: 'POST',
             path: '/v1/oauth/token',
@@ -193,6 +312,10 @@ export class AuthModule {
         if (player !== null) {
             const scope = response.data.scopes.includes('saves') ? 'profile saves' : 'profile';
             this.#writeSessionHint(browser.sessionStorage, scope);
+            const persistent = this.#persistentStorage(browser);
+            if (this.#config.crossSessionRestore !== null && persistent !== null) {
+                this.#writePersistentHint(persistent, scope);
+            }
         }
     }
     async #fetchPlayer(options) {
@@ -226,6 +349,9 @@ export class AuthModule {
         if (browser) {
             this.#removePending(browser.sessionStorage);
             this.#removeSessionHint(browser.sessionStorage);
+            const persistent = this.#persistentStorage(browser);
+            if (persistent !== null)
+                this.#removePersistentHint(persistent);
         }
         this.#setState(anonymous('logged_out'));
         if (token === null)
@@ -265,7 +391,12 @@ export class AuthModule {
             invalid: !sameCallbackBase(current, expected) || (code === null) === (error === null),
         };
     }
-    #cleanCallback(browser, url) {
+    /** Removes the callback fields; a silent attempt returns to the page that started it. */
+    #cleanCallback(browser, url, returnTo) {
+        if (returnTo !== null && isSafeReturnPath(returnTo)) {
+            browser.replaceUrl(returnTo);
+            return;
+        }
         const clean = new URL(url.toString());
         for (const key of CALLBACK_PARAMETERS)
             clean.searchParams.delete(key);
@@ -300,6 +431,15 @@ export class AuthModule {
                     globalThis.history.replaceState(globalThis.history.state, '', url);
                 },
                 sessionStorage: globalThis.sessionStorage,
+                get persistentStorage() {
+                    try {
+                        return typeof globalThis.localStorage === 'undefined' ? null : globalThis.localStorage;
+                    }
+                    catch {
+                        // Blocked storage (privacy settings, sandboxed frames).
+                        return null;
+                    }
+                },
                 crypto: globalThis.crypto,
             };
         }
@@ -325,6 +465,99 @@ export class AuthModule {
     #hintKey() {
         return `pixelume.oauth.session.${this.#config.clientId ?? 'unconfigured'}`;
     }
+    #persistentHintKey() {
+        return `pixelume.oauth.restore.${this.#config.clientId ?? 'unconfigured'}`;
+    }
+    #restoreAttemptKey() {
+        return `pixelume.oauth.restore-attempt.${this.#config.clientId ?? 'unconfigured'}`;
+    }
+    #persistentStorage(browser) {
+        try {
+            return browser.persistentStorage ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Persistent-hint helpers never throw: an unavailable `localStorage` only disables
+     * cross-session restoration, it must not break the login itself.
+     */
+    #readPersistentHint(storage, maxAgeMs) {
+        try {
+            const raw = storage.getItem(this.#persistentHintKey());
+            if (raw === null)
+                return null;
+            const value = JSON.parse(raw);
+            const now = Date.now();
+            if (!isPersistentHint(value) || value.at > now + 60_000 || value.at + maxAgeMs < now) {
+                storage.removeItem(this.#persistentHintKey());
+                return null;
+            }
+            return value;
+        }
+        catch {
+            this.#removePersistentHint(storage);
+            return null;
+        }
+    }
+    #writePersistentHint(storage, scope) {
+        const hint = { version: 1, scope, at: Date.now() };
+        try {
+            storage.setItem(this.#persistentHintKey(), JSON.stringify(hint));
+        }
+        catch {
+            // Quota or blocked storage: the next new tab simply starts as a visitor.
+        }
+    }
+    #downgradePersistentHint(storage) {
+        try {
+            const raw = storage.getItem(this.#persistentHintKey());
+            const value = raw === null ? null : JSON.parse(raw);
+            if (!isPersistentHint(value))
+                return;
+            storage.setItem(this.#persistentHintKey(), JSON.stringify({ ...value, scope: 'profile' }));
+        }
+        catch {
+            this.#removePersistentHint(storage);
+        }
+    }
+    #removePersistentHint(storage) {
+        try {
+            storage.removeItem(this.#persistentHintKey());
+        }
+        catch {
+            // Nothing else to do.
+        }
+    }
+    #recentRestoreAttempt(storage) {
+        const raw = storage.getItem(this.#restoreAttemptKey());
+        if (raw === null)
+            return false;
+        const at = Number(raw);
+        const now = Date.now();
+        if (!Number.isFinite(at) || at > now + 60_000 || at + AUTHORIZATION_REQUEST_TTL_MS < now) {
+            storage.removeItem(this.#restoreAttemptKey());
+            return false;
+        }
+        return true;
+    }
+    #writeRestoreAttempt(storage) {
+        try {
+            storage.setItem(this.#restoreAttemptKey(), String(Date.now()));
+        }
+        catch (cause) {
+            throw new PixelumeAuthError('storage_unavailable', { cause });
+        }
+    }
+    #removeRestoreAttempt(storage) {
+        try {
+            storage.removeItem(this.#restoreAttemptKey());
+        }
+        catch (cause) {
+            throw new PixelumeAuthError('storage_unavailable', { cause });
+        }
+    }
     #readPending(storage) {
         try {
             const raw = storage.getItem(this.#pendingKey());
@@ -408,11 +641,58 @@ function samePlayer(left, right) {
         left.displayName === right.displayName &&
         left.avatarUrl === right.avatarUrl);
 }
+function isPersistentHint(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const hint = value;
+    return (hint.version === 1 &&
+        (hint.scope === 'profile' || hint.scope === 'profile saves') &&
+        typeof hint.at === 'number' &&
+        Number.isFinite(hint.at));
+}
+function isOnline(browser) {
+    try {
+        if (typeof browser.isOnline === 'function')
+            return browser.isOnline();
+        const navigator = Reflect.get(globalThis, 'navigator');
+        return navigator?.onLine !== false;
+    }
+    catch {
+        return true;
+    }
+}
+/** Path, query and hash of `current` when it is on the redirect URI's origin; null otherwise. */
+function sameOriginPath(current, redirectUri) {
+    try {
+        const url = new URL(current);
+        if (url.origin !== new URL(redirectUri).origin)
+            return null;
+        for (const key of CALLBACK_PARAMETERS)
+            url.searchParams.delete(key);
+        const path = `${url.pathname}${url.search}${url.hash}`;
+        return isSafeReturnPath(path) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isSafeReturnPath(value) {
+    return (value.startsWith('/') &&
+        !value.startsWith('//') &&
+        !value.includes('\\') &&
+        value.length <= 2048);
+}
 function isPendingAuthorization(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value))
         return false;
     const pending = value;
-    return (pending.version === 1 &&
+    return ((pending.silent === undefined || pending.silent === true) &&
+        (pending.scope === undefined ||
+            pending.scope === 'profile' ||
+            pending.scope === 'profile saves') &&
+        (pending.returnTo === undefined ||
+            (typeof pending.returnTo === 'string' && isSafeReturnPath(pending.returnTo))) &&
+        pending.version === 1 &&
         typeof pending.state === 'string' &&
         /^[A-Za-z0-9_-]{43}$/u.test(pending.state) &&
         typeof pending.verifier === 'string' &&
@@ -461,6 +741,10 @@ function sameState(left, right) {
     if (left.status === 'anonymous' && right.status === 'anonymous') {
         return left.reason === right.reason && left.error === right.error;
     }
+    if ((left.status === 'redirecting' && right.status === 'redirecting') ||
+        (left.status === 'exchanging' && right.status === 'exchanging')) {
+        return left.restoring === right.restoring;
+    }
     return true;
 }
 //# sourceMappingURL=AuthModule.js.map