pryv 3.12.0 → 3.13.0

package/src/index.d.ts

@@ -684,6 +684,19 @@ declare module 'pryv' {
   export type AccessInfo =  Access & {
     calls: KeyValue;
     user: KeyValue;
+    /**
+     * Present when the access works through account delegation: a delegate
+     * token or an access granted through it (`isDelegatedAccess`, with
+     * `grantedVia: 'app'` for an app access granted by the delegate), or the
+     * control access of a delegation (`kind: 'control'`).
+     */
+    delegation?: {
+      isDelegatedAccess?: true;
+      kind?: 'control';
+      controlledUsername: string;
+      delegate: { username: string; hostSlug?: string };
+      grantedVia?: 'app';
+    };
   }
 
   export type EventAPICallRes = {
@@ -793,12 +806,16 @@ declare module 'pryv' {
     terms: string;
     eventTypes: string;
     version?: string;
+    /** Root URL of the platform's account app, when the platform names one. */
+    account?: string;
     assets?: {
       definitions: string;
     };
     serial?: string;
     features?: {
       noHF?: boolean;
+      /** Account delegation is available on this platform. */
+      delegation?: boolean;
       [key: string]: any;
     };
   };
@@ -964,7 +981,17 @@ declare module 'pryv' {
     | 'NEED_SIGNIN'
     | 'ACCEPTED'
     | 'SIGNOUT'
-    | 'REFUSED';
+    | 'REFUSED'
+    | 'SWITCHING';
+
+  /**
+   * An account remembered by the sign-in button. `actingAs` marks an account
+   * used through account delegation (`delegate`: the person acting).
+   */
+  export type AuthProfile = {
+    username: string;
+    actingAs?: { username: string; delegate: string };
+  };
 
   export type StateChangeTypes = {
     ERROR: {
@@ -998,9 +1025,31 @@ declare module 'pryv' {
       serviceInfo?: ServiceInfo;
       apiEndpoint: string;
       username: string;
+      /** Present on inline delivery; absent when a one-time `handoff` key is used. */
       token?: string;
+      /**
+       * Key of the auth request that just completed (use it with
+       * `connectFromKey`). Absent when the account comes from stored
+       * credentials: page load, an account switch without sign-in, or the
+       * return to the previous account after a switch that did not complete.
+       */
+      key?: string;
+      /** Display hint posted by the auth page for a grant on a controlled account; `accessInfo().delegation` is authoritative. */
+      delegation?: {
+        isDelegatedAccess: true;
+        controlledUsername: string;
+        delegate: { username: string; hostSlug?: string };
+      };
+      profile?: AuthProfile;
+      /** One-time credential hand-off key (shared-secret delivery), in place of `token`. */
+      handoff?: { type: 'shared-secret'; key: string };
     };
     SIGNOUT: {};
+    SWITCHING: {
+      from: string | null;
+      /** null: the account is chosen in the sign-in popup */
+      to: string | null;
+    };
     REFUSED: {
       reasonID?: string;
       message?: string;
@@ -1034,10 +1083,32 @@ declare module 'pryv' {
     serviceInfo?: ServiceInfo;
   };
 
+  /**
+   * Account menu entries of the sign-in button. `false` on an entry, or its
+   * name in `hide`, hides it.
+   */
+  export type LoginButtonMenuSettings = {
+    logout?: boolean;
+    account?: boolean;
+    info?: boolean;
+    /** Account switcher (remembered accounts, "Another account...", "Switch back"). */
+    switch?: boolean;
+    hide?: Array<'logout' | 'account' | 'info' | 'switch'>;
+  };
+
   export type AuthSettings = {
     spanButtonID?: string;
     onStateChange?: (state: StateChange<States>) => void;
     returnURL?: string;
+    /**
+     * Account menu shown when the signed-in button is clicked (default: on).
+     * `false` restores the plain logout confirmation.
+     */
+    menu?: LoginButtonMenuSettings | false;
+    /** Root URL of the account app; overrides the service's `account`. */
+    accountUrl?: string;
+    /** Most accounts remembered for this app (default 5); the least recently used is forgotten first. */
+    maxProfiles?: number;
     authRequest: {
       requestingAppId: string;
       languageCode?: string;
@@ -1048,7 +1119,20 @@ declare module 'pryv' {
       clientData?: KeyValue;
       deviceName?: string;
       expireAfter?: number;
+      /**
+       * Credential delivery mode. Defaults to `'shared-secret'`: the token is
+       * delivered through a one-time secret instead of the ACCEPTED poll, and
+       * `connectFromKey` redeems it. `'inline'` opts out (no field sent, legacy
+       * inline delivery). An older core ignores the field and delivers inline.
+       */
+      credentialHandoff?: 'shared-secret' | 'inline';
       serviceInfo?: Partial<ServiceInfo>;
+      /**
+       * Whether the sign-in may grant the access for an account the user
+       * controls through account delegation: 'allow' (server default),
+       * 'deny', or the username to preselect.
+       */
+      actAs?: 'allow' | 'deny' | string;
     };
   };
 
@@ -1072,6 +1156,7 @@ declare module 'pryv' {
     AUTHORIZED: 'ACCEPTED';
     SIGNOUT: 'SIGNOUT';
     REFUSED: 'REFUSED';
+    SWITCHING: 'SWITCHING';
   };
 
   type AuthStatePayload = {
@@ -1080,9 +1165,25 @@ declare module 'pryv' {
     error?: Error | unknown;
   };
 
-  export type StoredAuthorizationData = {
+  /** A remembered account as stored (credentials included). */
+  export type StoredAuthProfile = AuthProfile & {
     apiEndpoint: string;
-    username: string;
+    unavailable?: true;
+  };
+
+  /**
+   * Stored sign-in data. The top-level `apiEndpoint` / `username` are the
+   * active account (absent after logging out of one of several accounts);
+   * `profiles` lists every remembered account, most recently used first.
+   * The default button stores the two parts in two cookies.
+   */
+  export type StoredAuthorizationData = {
+    apiEndpoint?: string;
+    username?: string;
+    actingAs?: AuthProfile['actingAs'];
+    /** Auth page of the sign-in (without query), kept to locate the account app. */
+    authUrl?: string;
+    profiles?: StoredAuthProfile[];
   } | null;
 
   export type CustomLoginButton = {
@@ -1093,6 +1194,12 @@ declare module 'pryv' {
     saveAuthorizationData?: (authData: StoredAuthorizationData) => void;
     deleteAuthorizationData?: () => Promise<void>;
     finishAuthProcessAfterRedirection?: (authController: AuthController) => Promise<void>;
+    /**
+     * Called when the signed-in button is clicked. Return `false` to fall
+     * back to the SIGNOUT state (logout confirmation); log out from the menu
+     * with `AuthController.signOut()`.
+     */
+    showMenu?: () => boolean | void;
   };
 
   export class LoginButton implements CustomLoginButton {
@@ -1115,6 +1222,11 @@ declare module 'pryv' {
     saveAuthorizationData(authData: StoredAuthorizationData): void;
     deleteAuthorizationData(): Promise<void>;
     finishAuthProcessAfterRedirection(authController: AuthController): Promise<void>;
+    showMenu(): boolean;
+    /** Resolves when the re-initialization it may start (a dismissed "Log out?") is done. */
+    closeMenu(): Promise<void>;
+    /** The re-initialization started by the last menu action, if any. */
+    pending?: Promise<void>;
   }
 
   export class AuthController {
@@ -1140,7 +1252,30 @@ declare module 'pryv' {
       windowLocationForTest?: string,
       navigatorForTests?: string,
     ): string | boolean;
-    startAuthRequest(): Promise<AuthRequestResponse>;
+    /** `overrides`: auth request fields for this request only; `previous`: state to return to if an account switch does not complete. */
+    startAuthRequest(overrides?: Partial<AuthSettings['authRequest']>, previous?: AuthStatePayload): Promise<AuthRequestResponse>;
+    /**
+     * Log out: emits SIGNOUT once, forgets the active account (every
+     * remembered account with `all`), re-initializes.
+     */
+    signOut(options?: { all?: boolean }): Promise<void>;
+    /** The remembered accounts, most recently used first. */
+    profiles(): Array<AuthProfile & { active: boolean; available: boolean }>;
+    /** The signed-in account, or null. */
+    currentProfile(): AuthProfile | null;
+    /**
+     * Switch account (`null`: the signed-in person's own account). A
+     * remembered account with a valid access needs no sign-in; otherwise the
+     * auth request runs again with `actAs`. Emits SWITCHING, ends in ACCEPTED,
+     * or back on the previous account when the sign-in is refused.
+     */
+    switchTo(username: string | null): Promise<void>;
+    /** Sign in to one more account (`actAs: 'allow'`), keeping the remembered ones. */
+    addAccount(): Promise<void>;
+    /** Account app profile URL, or null when it cannot be determined. */
+    accountUrl(): string | null;
+    /** Opens the account app in a new tab; returns the URL, or null. */
+    openAccountApp(): string | null;
     set state(newState: AuthStatePayload);
     get state(): AuthStatePayload;
   }

package/src/lib/handoff.js

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+
+/**
+ * Credential hand-off (shared-secret delivery) support for the auth-request
+ * flow.
+ *
+ * When an access request set `credentialHandoff: 'shared-secret'`, the ACCEPTED
+ * poll body carries a one-time `handoff.key` and a token-less `apiEndpoint`
+ * instead of the token. This module redeems that key ONCE against the user's
+ * core (`shared-secrets/retrieve`, no credentials needed) and turns the result
+ * into a token-bearing apiEndpoint the rest of the library already understands.
+ *
+ * A module-level cache keyed by the auth-flow poll key holds the result for a
+ * short TTL: `pryv.connectFromKey(key, ...)` builds a fresh `Service` on every
+ * call and the `AuthController` polling loop also reads the ACCEPTED body, so
+ * without a shared cache the one-shot secret would be redeemed twice and the
+ * second read would fail. Whoever redeems first fills the cache; the others
+ * reuse it.
+ */
+
+const utils = require('../utils');
+const SharedSecrets = require('../SharedSecrets');
+const PryvError = require('./PryvError');
+
+/** How long a redeemed credential stays cached (10 min, or until sign-out). */
+const TTL_MS = 10 * 60 * 1000;
+
+/** poll key -> { apiEndpoint, username, token, expiresAt } */
+const cache = new Map();
+/** poll key -> Promise, so concurrent resolves for one key redeem once. */
+const inflight = new Map();
+
+function cacheGet (key) {
+  if (key == null) return null;
+  const entry = cache.get(key);
+  if (entry == null) return null;
+  if (Date.now() > entry.expiresAt) {
+    cache.delete(key);
+    return null;
+  }
+  return entry;
+}
+
+/** Drop expired entries so cached tokens do not linger for the process
+ * lifetime in a long-running Node service (a browser page is short-lived, but
+ * the same module runs server-side too). Called on every set; the map holds
+ * one entry per in-flight sign-in, so the scan is trivially small. */
+function sweep () {
+  const now = Date.now();
+  for (const [k, entry] of cache) {
+    if (now > entry.expiresAt) cache.delete(k);
+  }
+}
+
+function cacheSet (key, value) {
+  if (key == null) return;
+  sweep();
+  cache.set(key, Object.assign({}, value, { expiresAt: Date.now() + TTL_MS }));
+}
+
+/** Drop one entry (sign-out). Passing no key is an explicit clear-all. */
+function cacheClear (key) {
+  if (arguments.length === 0) cache.clear();
+  else cache.delete(key);
+}
+
+/** Does an ACCEPTED poll body deliver by shared-secret hand-off? */
+function isHandoffBody (body) {
+  return body != null && body.handoff != null &&
+    body.handoff.type === 'shared-secret' && typeof body.handoff.key === 'string';
+}
+
+/**
+ * Redeem a hand-off poll body into a token-bearing apiEndpoint, caching the
+ * result under `cacheKey`. Throws a `PryvError` (id `credential-handoff-failed`)
+ * telling the caller to restart the auth request when the one-time secret is
+ * gone (already redeemed, expired) or the retrieve fails.
+ *
+ * @param {Object} pollBody an ACCEPTED body carrying `apiEndpoint` + `handoff.key`
+ * @param {string} [cacheKey] the auth-flow poll key, so a repeat resolve reuses this
+ * @returns {Promise<{ apiEndpoint: string, username: string, token: string }>}
+ */
+async function resolveHandoff (pollBody, cacheKey) {
+  const cached = cacheGet(cacheKey);
+  if (cached != null) return cached;
+  // De-duplicate concurrent redemptions of the same key (e.g. React
+  // StrictMode double-invoking an effect that calls connectFromKey twice):
+  // both would otherwise miss the cache and the second would 403 the
+  // already-consumed one-time secret.
+  if (cacheKey != null && inflight.has(cacheKey)) return inflight.get(cacheKey);
+
+  const promise = doResolve(pollBody, cacheKey);
+  if (cacheKey == null) return promise;
+  inflight.set(cacheKey, promise);
+  try {
+    return await promise;
+  } finally {
+    inflight.delete(cacheKey);
+  }
+}
+
+async function doResolve (pollBody, cacheKey) {
+  let result;
+  try {
+    result = await SharedSecrets.retrieve(pollBody.apiEndpoint, pollBody.handoff.key);
+  } catch (err) {
+    const pe = new PryvError(
+      'Credential hand-off could not be retrieved (' +
+        (err && (err.id || err.message)) + '); restart the auth request.',
+      err
+    );
+    // Stable id for callers that branch on the hand-off failure; the finer
+    // reason (`shared-secret-unavailable`) rides on `innerObject.id`, which
+    // `SharedSecrets.retrieve` now takes from the refusal's `data.id`.
+    pe.id = 'credential-handoff-failed';
+    throw pe;
+  }
+
+  const secret = (result && result.secret) || {};
+  if (typeof secret.token !== 'string' || typeof secret.apiEndpoint !== 'string') {
+    const pe = new PryvError('Credential hand-off returned an incomplete secret.');
+    pe.id = 'credential-handoff-failed';
+    throw pe;
+  }
+
+  // The secret's apiEndpoint may be token-less or token-bearing; rebuild a
+  // canonical token-bearing endpoint from the authoritative `token` so the
+  // rest of the library (Connection, the LoginButton cookie) is unchanged.
+  const { endpoint } = utils.extractTokenAndAPIEndpoint(secret.apiEndpoint);
+  const apiEndpoint = utils.buildAPIEndpoint({ endpoint, token: secret.token });
+  const entry = { apiEndpoint, username: secret.username, token: secret.token };
+  cacheSet(cacheKey, entry);
+  return entry;
+}
+
+module.exports = { resolveHandoff, isHandoffBody, cacheGet, cacheSet, cacheClear };

package/test/AuthController.test.js

@@ -59,6 +59,20 @@ describe('[ACNX] AuthController', function () {
         authRequest: { requestingAppId: 'test-app' }
       }, service)).to.throw('Missing settings.authRequest.requestedPermissions');
     });
+
+    it('[ACVE] defaults the request to shared-secret credential hand-off', function () {
+      const settings = { authRequest: { requestingAppId: 'test-app', requestedPermissions: [] } };
+      // eslint-disable-next-line no-new
+      new AuthController(settings, service);
+      expect(settings.authRequest.credentialHandoff).to.equal('shared-secret');
+    });
+
+    it('[ACVF] credentialHandoff:\'inline\' opts out and sends no field', function () {
+      const settings = { authRequest: { requestingAppId: 'test-app', requestedPermissions: [], credentialHandoff: 'inline' } };
+      // eslint-disable-next-line no-new
+      new AuthController(settings, service);
+      expect(settings.authRequest).to.not.have.property('credentialHandoff');
+    });
   });
 
   describe('[ACLX] Listeners', function () {
@@ -133,6 +147,125 @@ describe('[ACNX] AuthController', function () {
     });
   });
 
+  describe('[ACUX] account app URL and signOut', function () {
+    function controller (extraSettings) {
+      return new AuthController(Object.assign({
+        authRequest: { requestingAppId: 'test-app', requestedPermissions: [] }
+      }, extraSettings), service);
+    }
+    const profile = (base) => base + '/account/profile?pryvServiceInfoUrl=' + encodeURIComponent(testData.serviceInfoUrl);
+
+    it('[ACUA] resolves settings.accountUrl, then the service account, then the auth page URL', async function () {
+      const auth = controller({ accountUrl: 'https://own.example.com/' });
+      await auth.init();
+      auth.serviceInfo = Object.assign({}, auth.serviceInfo, { account: 'https://account.example.com' });
+      auth._authUrl = 'https://ui.example.com/auth?key=abc';
+      expect(auth.accountUrl()).to.equal(profile('https://own.example.com'));
+      delete auth.settings.accountUrl;
+      expect(auth.accountUrl()).to.equal(profile('https://account.example.com'));
+      delete auth.serviceInfo.account;
+      expect(auth.accountUrl()).to.equal(profile('https://ui.example.com'));
+    });
+
+    it('[ACUB] is null when nothing names the account app', async function () {
+      const auth = controller();
+      await auth.init();
+      auth.serviceInfo = Object.assign({}, auth.serviceInfo);
+      delete auth.serviceInfo.account;
+      expect(auth.accountUrl()).to.equal(null);
+      for (const authUrl of ['https://ui.example.com/access/login?key=x', 'not a url', 'https://ui.example.com/authorize']) {
+        auth._authUrl = authUrl;
+        expect(auth.accountUrl(), authUrl).to.equal(null);
+      }
+    });
+
+    it('[ACUC] openAccountApp opens the profile page in a new tab without an opener', async function () {
+      const auth = controller({ accountUrl: 'https://own.example.com' });
+      await auth.init();
+      const opened = [];
+      const original = window.open;
+      window.open = (...args) => { opened.push(args); return null; };
+      try {
+        expect(auth.openAccountApp()).to.equal(profile('https://own.example.com'));
+      } finally { window.open = original; }
+      expect(opened).to.deep.equal([[profile('https://own.example.com'), '_blank', 'noopener']]);
+    });
+
+    it('[ACUD] signOut emits SIGNOUT once, clears the stored credentials and re-initializes', async function () {
+      const states = [];
+      let deleted = 0;
+      const button = {
+        getAuthorizationData: () => null,
+        deleteAuthorizationData: async () => { deleted++; },
+        onStateChange: async () => {},
+        onClick: () => {}
+      };
+      const auth = new AuthController({
+        authRequest: { requestingAppId: 'test-app', requestedPermissions: [] },
+        onStateChange: (s) => states.push(s.status)
+      }, service, button);
+      await auth.init();
+      auth._state = { status: AuthStates.AUTHORIZED, username: 'u' };
+      states.length = 0;
+      await auth.signOut();
+      expect(states.filter((s) => s === AuthStates.SIGNOUT)).to.have.lengthOf(1);
+      expect(deleted).to.equal(1);
+      expect(auth.state.status).to.equal(AuthStates.INITIALIZED);
+    });
+
+    it('[ACUF] the auth page URL of a sign-in locates the account app, and survives a reload', async function () {
+      const utils = require('../src/utils');
+      const { fetchPost, fetchGet } = utils;
+      utils.fetchPost = async () => ({ response: { ok: true }, body: { status: AuthStates.NEED_SIGNIN, key: 'k1', poll: 'https://core.example.com/reg/access/k1', poll_rate_ms: 1, authUrl: 'https://ui.example.com/auth?key=k1' } });
+      utils.fetchGet = async () => ({ response: { status: 200 }, body: { status: AuthStates.AUTHORIZED, username: 'u', token: 't', apiEndpoint: 'https://t@u.example.com/' } });
+      let saved = null;
+      const button = {
+        getAuthorizationData: () => saved,
+        saveAuthorizationData: (d) => { saved = d; },
+        onStateChange: async (state) => {
+          if (state.status === AuthStates.AUTHORIZED) saved = { apiEndpoint: state.apiEndpoint, username: state.username, authUrl: auth._authUrl };
+        },
+        onClick: () => {}
+      };
+      const auth = new AuthController({ authRequest: { requestingAppId: 'test-app', requestedPermissions: [] } }, service, button);
+      try {
+        await auth.init();
+        auth.serviceInfo = Object.assign({}, auth.serviceInfo, { account: undefined });
+        await auth.startAuthRequest();
+      } finally { utils.fetchPost = fetchPost; utils.fetchGet = fetchGet; }
+      expect(auth.accountUrl()).to.equal(profile('https://ui.example.com'));
+
+      // a new page load: only the stored data is known
+      const reloaded = new AuthController({ authRequest: { requestingAppId: 'test-app', requestedPermissions: [] } }, service, button);
+      await reloaded.init();
+      reloaded.serviceInfo = Object.assign({}, reloaded.serviceInfo, { account: undefined });
+      expect(reloaded.state.status).to.equal(AuthStates.AUTHORIZED);
+      expect(reloaded.accountUrl()).to.equal(profile('https://ui.example.com'));
+    });
+
+    it('[ACUE] a button with showMenu gets the click instead of SIGNOUT, unless it declines', async function () {
+      for (const [answer, expectSignout] of [[true, false], [undefined, false], [false, true]]) {
+        const states = [];
+        let menus = 0;
+        const button = {
+          getAuthorizationData: () => null,
+          onStateChange: async () => {},
+          onClick: () => {},
+          showMenu: () => { menus++; return answer; }
+        };
+        const auth = new AuthController({
+          authRequest: { requestingAppId: 'test-app', requestedPermissions: [] },
+          onStateChange: (s) => states.push(s.status)
+        }, service, button);
+        await auth.init();
+        auth._state = { status: AuthStates.AUTHORIZED };
+        await auth.handleClick();
+        expect(menus).to.equal(1);
+        expect(states.includes(AuthStates.SIGNOUT), 'showMenu returned ' + answer).to.equal(expectSignout);
+      }
+    });
+  });
+
   describe('[ACSX] stopAuthRequest', function () {
     it('[ACSA] sets error state with message', async function () {
       const auth = new AuthController({
@@ -264,4 +397,81 @@ describe('[ACNX] AuthController', function () {
       expect(last.message).to.equal('boom');
     });
   });
+
+  describe('[ACGX] credential hand-off polling', function () {
+    let realFetch;
+    let handoffKeyCounter = 0;
+
+    /** Stub the whole flow: access POST -> NEED_SIGNIN, poll GET -> pollBody,
+     *  shared-secrets/retrieve -> retrieveResponse. */
+    function stubFlow (pollBody, retrieveResponse) {
+      realFetch = global.fetch;
+      global.fetch = async function (url, options) {
+        const u = String(url);
+        if (u.includes('shared-secrets/retrieve')) {
+          return {
+            ok: retrieveResponse.ok !== false,
+            status: retrieveResponse.status || 200,
+            json: async () => retrieveResponse.body
+          };
+        }
+        if (options && options.method === 'POST' && u.includes('/access')) {
+          return {
+            ok: true,
+            status: 201,
+            json: async () => ({
+              status: 'NEED_SIGNIN',
+              key: 'ho-key-' + (++handoffKeyCounter),
+              poll: 'https://reg.test.local/access/pk' + handoffKeyCounter,
+              poll_rate_ms: 5
+            })
+          };
+        }
+        if (u.includes('/access/')) { // the poll GET
+          return { ok: true, status: 200, json: async () => pollBody };
+        }
+        return { ok: true, status: 200, json: async () => ({}) };
+      };
+    }
+
+    afterEach(function () {
+      if (realFetch) global.fetch = realFetch;
+      realFetch = null;
+    });
+
+    function makeAuth () {
+      const auth = new AuthController({
+        authRequest: { requestingAppId: 'test-app', requestedPermissions: [] }
+      }, service);
+      // Skip init() (asset loading): set the service info the flow needs.
+      auth.serviceInfo = { access: 'https://reg.test.local/access', register: 'https://reg.test.local/' };
+      return auth;
+    }
+
+    it('[ACGA] redeems a hand-off ACCEPTED body and rewrites the internal state to the legacy shape (token, no handoff)', async function () {
+      stubFlow(
+        { status: 'ACCEPTED', username: 'eve', apiEndpoint: 'https://eve.test.local/', handoff: { type: 'shared-secret', key: 'evt.' + 'e'.repeat(40) } },
+        { body: { secret: { username: 'eve', token: 'tok-eve', apiEndpoint: 'https://eve.test.local/' } } }
+      );
+      const auth = makeAuth();
+      await auth.startAuthRequest();
+      expect(auth.state.status).to.equal(AuthStates.AUTHORIZED);
+      expect(auth.state.token).to.equal('tok-eve');
+      expect(auth.state.apiEndpoint).to.contain('tok-eve@');
+      expect(auth.state.apiEndpoint).to.contain('eve.test.local');
+      // The one-time key must not survive into the state the cookie/listener see.
+      expect(auth.state.handoff).to.equal(undefined);
+    });
+
+    it('[ACGB] a failed hand-off retrieve puts the controller in ERROR, not a broken AUTHORIZED', async function () {
+      stubFlow(
+        { status: 'ACCEPTED', username: 'frank', apiEndpoint: 'https://frank.test.local/', handoff: { type: 'shared-secret', key: 'evt.' + 'f'.repeat(40) } },
+        { ok: false, status: 403, body: { error: { id: 'forbidden', message: 'used', data: { id: 'shared-secret-unavailable' } } } }
+      );
+      const auth = makeAuth();
+      await auth.startAuthRequest();
+      expect(auth.state.status).to.equal(AuthStates.ERROR);
+      expect(auth.state.token).to.equal(undefined);
+    });
+  });
 });

package/test/Browser.AuthController.test.js

@@ -112,9 +112,10 @@ describe('[AUTX] Browser.LoginButton', function () {
       const seen = [];
       const a = makeAuth((s) => seen.push(s.status));
       await a.init();
-      // Mimic LoginButton (registered after the external app listener): on
-      // SIGNOUT it confirms + re-initializes, synchronously driving the state
-      // to INITIALIZED during the same dispatch.
+      // Worst case of a LoginButton-like listener (registered after the external
+      // app listener): on SIGNOUT it re-initializes synchronously, driving the
+      // state to INITIALIZED during the same dispatch. (The real LoginButton
+      // awaits its re-init, which starts a microtask later.)
       a.stateChangeListeners.push((s) => {
         if (s.status === AuthStates.SIGNOUT) a.state = { status: AuthStates.INITIALIZED, serviceInfo: {} };
       });