@pixelume/sdk 0.3.0 → 0.5.0

package/dist/modules/auth/AuthModule.js

@@ -1,25 +1,68 @@
 import { parseEmptyResponse, parseOAuthTokenResponse, parsePlayerEnvelope, } from '../../contracts/index.js';
-import { PixelumeAuthError, PixelumeConfigError, PixelumeHttpError, isPixelumeError, } from '../../core/errors.js';
+import { PixelumeAuthError, PixelumeConfigError, isPixelumeError, } from '../../core/errors.js';
+import { SessionManager, browserResumeSource, } from './SessionManager.js';
 const AUTHORIZATION_REQUEST_TTL_MS = 10 * 60_000;
-const TOKEN_EXPIRY_SKEW_MS = 5_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;
     #listeners = new Set();
     #state = Object.freeze({ status: 'uninitialized', player: null });
-    #token = null;
+    #session;
     #initializePromise = null;
     #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: this.#resume,
+            onEnded: (error) => {
+                this.#setState(anonymous('expired', error));
+            },
+        });
     }
     get state() {
         return this.#state;
     }
+    get session() {
+        return this.#session.state;
+    }
+    /** @internal Shared with feature modules that call Bearer-protected routes. */
+    get sessionManager() {
+        return this.#session;
+    }
+    subscribeSession(listener) {
+        return this.#session.subscribe(listener);
+    }
+    refresh(options = {}) {
+        return this.#session.refresh(options);
+    }
+    /** @internal Releases timers/listeners and drops credentials from memory (no revocation). */
+    dispose() {
+        this.#stopRestoreWatch?.();
+        this.#stopRestoreWatch = null;
+        this.#session.dispose();
+        this.#listeners.clear();
+    }
     initialize() {
         this.#initializePromise ??= this.#doInitialize();
         return this.#initializePromise;
@@ -29,23 +72,18 @@ export class AuthModule {
         return () => this.#listeners.delete(listener);
     }
     login(options = {}) {
-        const scope = options.scope;
-        if (scope !== undefined && scope !== 'profile') {
-            return Promise.reject(new PixelumeConfigError('Pixelume Auth supports only the "profile" scope'));
+        const scope = options.scope ?? this.#config.scope;
+        if (scope !== 'profile' && scope !== 'profile saves') {
+            return Promise.reject(new PixelumeConfigError('Pixelume Auth scope must be "profile" or "profile saves"'));
         }
-        this.#loginPromise ??= this.#doLogin().finally(() => {
+        this.#loginPromise ??= this.#doLogin(scope, false).finally(() => {
             this.#loginPromise = null;
         });
         return this.#loginPromise;
     }
     getPlayer(options = {}) {
-        if (this.#token === null)
+        if (!this.#session.active)
             return Promise.resolve(null);
-        if (this.#token.expiresAt <= Date.now() + TOKEN_EXPIRY_SKEW_MS) {
-            this.#token = null;
-            this.#setState(anonymous('expired'));
-            return Promise.resolve(null);
-        }
         this.#playerPromise ??= this.#fetchPlayer(options).finally(() => {
             this.#playerPromise = null;
         });
@@ -64,34 +102,92 @@ export class AuthModule {
             if (callback !== null) {
                 await this.#handleCallback(browser, callback);
             }
-            else if (this.#config.restoreSession && this.#readSessionHint(browser.sessionStorage)) {
-                this.#removeSessionHint(browser.sessionStorage);
-                await this.login();
-            }
             else {
-                this.#setState(anonymous('visitor'));
+                const persistent = this.#persistentStorage(browser);
+                if (this.#config.crossSessionRestore !== null && persistent !== null) {
+                    await this.#restoreAcrossSessions(browser, persistent, this.#config.crossSessionRestore);
+                }
+                else {
+                    // The feature was turned off: do not leave a stale hint behind.
+                    if (persistent !== null)
+                        this.#removePersistentHint(persistent);
+                    await this.#restoreSameTab(browser);
+                }
             }
         }
         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() {
+    /** 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);
         }
@@ -104,9 +200,14 @@ export class AuthModule {
             state: pending.state,
             code_challenge: challenge,
             code_challenge_method: 'S256',
-            scope: 'profile',
+            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());
         }
@@ -114,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)) {
@@ -136,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;
@@ -144,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',
@@ -158,57 +307,65 @@ export class AuthModule {
             },
             parse: parseOAuthTokenResponse,
         });
-        this.#token = {
-            value: response.data.access_token,
-            expiresAt: Date.now() + response.data.expires_in * 1_000,
-        };
+        this.#session.start(response.data);
         const player = await this.getPlayer();
-        if (player !== null)
-            this.#writeSessionHint(browser.sessionStorage);
+        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) {
-        const token = this.#token;
-        if (token === null)
-            return null;
         try {
-            const response = await this.#http.request({
+            const response = await this.#session.authorizedRequest({
                 method: 'GET',
                 path: '/v1/oauth/userinfo',
-                credentials: 'omit',
-                headers: { authorization: `Bearer ${token.value}` },
                 signal: options.signal,
                 timeoutMs: options.timeoutMs,
                 parse: parsePlayerEnvelope,
             });
             const player = Object.freeze({ ...response.data.player });
+            const current = this.#state;
+            // Keep the same object when nothing changed, so renewals do not look like a new login.
+            if (current.status === 'authenticated' && samePlayer(current.player, player)) {
+                return current.player;
+            }
             this.#setState(Object.freeze({ status: 'authenticated', player }));
             return player;
         }
         catch (error) {
-            if (error instanceof PixelumeHttpError && error.status === 401) {
-                this.#token = null;
-                this.#setState(anonymous('expired'));
+            // The session ended (expired/revoked); the state already reflects it.
+            if (error instanceof PixelumeAuthError)
                 return null;
-            }
             throw error;
         }
     }
     async #doLogout(options) {
-        const token = this.#token;
-        this.#token = null;
+        const token = this.#session.reset();
         const browser = this.#optionalBrowser();
         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)
             return;
+        // Revoking any token of the family revokes all of it; the refresh token is the preferred hint.
         await this.#http.request({
             method: 'POST',
             path: '/v1/oauth/revoke',
             credentials: 'omit',
-            form: { token: token.value, token_type_hint: 'access_token' },
+            form: {
+                token: token.refreshToken ?? token.accessToken,
+                token_type_hint: token.refreshToken === null ? 'access_token' : 'refresh_token',
+                client_id: this.#requireClientId(),
+            },
             signal: options.signal,
             timeoutMs: options.timeoutMs,
             parse: parseEmptyResponse,
@@ -234,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);
@@ -269,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,
             };
         }
@@ -294,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());
@@ -326,17 +590,23 @@ export class AuthModule {
             throw new PixelumeAuthError('storage_unavailable', { cause });
         }
     }
+    /** The hint is non-secret: only "a session existed" and the scope that was granted. */
     #readSessionHint(storage) {
         try {
-            return storage.getItem(this.#hintKey()) === '1';
+            const value = storage.getItem(this.#hintKey());
+            if (value === '1' || value === 'profile')
+                return 'profile';
+            if (value === 'profile saves')
+                return 'profile saves';
+            return null;
         }
         catch (cause) {
             throw new PixelumeAuthError('storage_unavailable', { cause });
         }
     }
-    #writeSessionHint(storage) {
+    #writeSessionHint(storage, scope) {
         try {
-            storage.setItem(this.#hintKey(), '1');
+            storage.setItem(this.#hintKey(), scope);
         }
         catch (cause) {
             throw new PixelumeAuthError('storage_unavailable', { cause });
@@ -366,11 +636,63 @@ export class AuthModule {
 function anonymous(reason, error = null) {
     return Object.freeze({ status: 'anonymous', player: null, reason, error });
 }
+function samePlayer(left, right) {
+    return (left.id === right.id &&
+        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' &&
@@ -419,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