Source: accounts.js

import { subjectMatches } from './caep/subjects.js';
import { GNAPClientError } from './errors.js';
import { GrantSet } from './grant-set.js';
import { IndexedDBTokenStore, MemoryTokenStore, WebStorageTokenStore } from './stores.js';
import { TokenManager } from './token-manager.js';
import { base64url, digest, Emitter, withLock } from './util.js';

/** Identity claims an account record keeps, for display and for matching security events. No tokens. */
const PROFILE_CLAIMS = ['iss', 'sub', 'uid', 'account', 'name', 'given_name', 'family_name', 'preferred_username', 'email',
  'email_verified', 'phone_number', 'phone_number_verified', 'picture', 'acr', 'amr', 'auth_time'];

/**
 * @typedef {object} Account  One person signed in through this client in this browser. Holds no token.
 * @property {string} key          Stable id derived from `iss` and `sub`.
 * @property {string} iss
 * @property {string} sub
 * @property {string[]} [sessions] The session ids iya-sts names this account's grant by in a CAEP event:
 *           `gnap-grant:<id>` and `gnap-token:<jti>`.
 * @property {string} [grantId]
 * @property {string} [uid]        The person's username at the AS, from an `account` subject identifier.
 * @property {string} [name]
 * @property {string} [email]
 * @property {string} [preferred_username]
 * @property {'signed-in'|'tokens-missing'|'signed-out'|'ended'} status
 *           `signed-in`: its grant is in the cache. `tokens-missing`: not signed out, but its access token
 *           expired and could not be rotated; `reauthenticate()` asks for a new grant. `ended`: ended by
 *           the AS, a security event or a refused rotation; see `endedReason`.
 * @property {string} [endedReason]
 * @property {number} addedAt
 * @property {number} lastUsedAt
 * @property {number} [changedAt]  When the status last left `signed-in`.
 */

/**
 * @callback AccountHook
 * @param {Account} account
 * @param {{ getTokenSet: (opts?: { forceRefresh?: boolean }) => Promise<GrantSet> }} access
 *        Reaches this account's grant during the hook (and, for `onActivate`, for as long as it stays active).
 * @returns {unknown} Anything; a promise is awaited.
 */

/**
 * @typedef {object} AccountManagerOptions
 * @property {import('./stores.js').TokenStore} [store]  The cache shared by every tab: the account list and
 *           each account's grant. Default: IndexedDB (`IndexedDBTokenStore`) when tokens are key-bound
 *           (`requireBoundTokens`, the default), else memory.
 * @property {import('./stores.js').TokenStore} [tabStore]  Where this tab remembers its active account.
 *           Default: sessionStorage where it exists, else memory.
 * @property {string} [storeKey]                Default "accounts".
 * @property {number} [refreshSkewSec]          Default 60.
 * @property {number} [maxAccounts]             Default 10.
 * @property {number} [rememberSignedOutDays]   How long a signed-out account stays listed. Default 30.
 * @property {AccountHook} [onActivate]  Runs when an account is about to become this tab's active account,
 *           after its token is rotated if due and before "activated" is emitted — e.g. to poll its CAEP
 *           stream and act on the signals queued while it was dormant. Throwing aborts the activation.
 * @property {(account: Account) => void|Promise<void>} [onDeactivate]  Runs when an account stops being
 *           this tab's active account (e.g. to stop polling its stream).
 * @property {AccountHook} [onLeave]  Runs before an account's grant is dropped by `signOut()` or `end()`
 *           (e.g. to delete its CAEP stream while its token still works).
 * @property {boolean} [broadcast]  Tell this origin's other tabs about changes (BroadcastChannel). Default true.
 */

/**
 * Every person signed in through one GNAP client in this browser, with ONE active account per tab.
 *
 * - **One cache, shared by every tab.** Each account's grant (access token, management and continuation)
 *   is kept until the account is signed out or its grant ends, so any tab can make any signed-in account
 *   active with no trip to the AS.
 * - **One active account per tab.** Only its token is reachable (`getTokenSet()`), and only its token is
 *   rotated in the background. The others are dormant. `activate(key)` rotates a dormant account's token
 *   if due and runs `onActivate` before it becomes active.
 * - Rotations hold a lock shared by the tabs (Web Locks); sign-outs and ended grants are announced to the
 *   other tabs (BroadcastChannel).
 *
 * Signing in: `signIn()` / `addAccount()` start a grant the AS decides on (its account picker when several
 * people are signed in there). `reauthenticate(key)` names the person in the request's `user` and refuses
 * a grant approved by anybody else. `signOut(key)` revokes that account's grant at the AS.
 *
 * Events: "added" (account), "updated" (account), "activated" (account|undefined, previous|undefined),
 * "rotated" (account) for the active account, "signed-out" (account), "ended" (account, reason),
 * "forgotten" (account), "activation_error" (account, error), and "change" after any of them, including
 * changes made in another tab.
 */
export class AccountManager extends Emitter {
  #client;
  #tokens;
  #store;
  #tabStore;
  #storeKey;
  #opts;
  /** @type {Map<string, Account>} */
  #accounts = new Map();
  #active;
  #activating;
  #mutating;
  #channel;

  /**
   * @param {import('./gnap-client.js').GNAPClient} client
   * @param {AccountManagerOptions} [opts]
   */
  constructor(client, {
    store, tabStore, storeKey = 'accounts', refreshSkewSec = 60, maxAccounts = 10, rememberSignedOutDays = 30,
    onActivate, onDeactivate, onLeave, broadcast = true,
  } = {}) {
    super();
    this.#client = client;
    // Tokens at rest need a sender constraint. GNAP tokens are bound to the client key unless the AS issued
    // a bearer token, which `requireBoundTokens` (the default) refuses.
    const bound = client.config?.requireBoundTokens !== false;
    this.#store = store ?? (bound && typeof indexedDB !== 'undefined' ? new IndexedDBTokenStore() : new MemoryTokenStore());
    if (store && !bound && !(store instanceof MemoryTokenStore)) {
      console.warn('[gnap-caep-client] AccountManager: bearer tokens may be kept in persistent browser storage. '
        + 'Any script in the page can read them and use them anywhere; keep requireBoundTokens on or use MemoryTokenStore.');
    }
    this.#tabStore = tabStore ?? (globalThis.sessionStorage ? new WebStorageTokenStore({ prefix: 'gnap-caep-client:tab:' }) : new MemoryTokenStore());
    this.#storeKey = storeKey;
    this.#opts = { maxAccounts, rememberSignedOutDays, refreshSkewSec, onActivate, onDeactivate, onLeave };
    this.#tokens = new TokenManager(client, { store: this.#store, refreshSkewSec });
    this.#tokens.on('rotated', (key, ts) => { this.#onRotated(key, ts).catch(() => {}); });
    this.#tokens.on('expired', (key) => { this.end(key, 'Its access token could not be renewed.').catch(() => {}); });
    if (broadcast && typeof BroadcastChannel !== 'undefined') {
      this.#channel = new BroadcastChannel(`gnap-caep-client:${storeKey}`);
      this.#channel.onmessage = () => { this.#onRemoteChange().catch(() => {}); };
      this.#channel.unref?.();
    }
  }

  /**
   * Loads the shared account list and reactivates the account this tab had active. A failed reactivation
   * leaves the tab with no active account and is emitted as "activation_error".
   */
  async init() {
    const forgetBefore = Date.now() - this.#opts.rememberSignedOutDays * 86_400_000;
    await this.#mutate(() => {
      for (const a of [...this.#accounts.values()]) {
        if (a.status === 'signed-out' && (a.changedAt ?? 0) < forgetBefore) this.#accounts.delete(a.key);
      }
    });
    const remembered = await this.#tabStore.get(this.#tabKey());
    if (remembered && this.#accounts.has(remembered)) {
      try {
        await this.#activate(remembered);
      } catch (err) {
        this.emit('activation_error', this.get(remembered), err);
      }
    }
    return this;
  }

  /** @returns {Account[]} Every account in this browser, in the order added. */
  list() {
    return [...this.#accounts.values()].sort((a, b) => a.addedAt - b.addedAt).map((a) => ({ ...a }));
  }

  /** @param {string} key @returns {Account|undefined} */
  get(key) {
    const a = this.#accounts.get(key);
    return a && { ...a };
  }

  /** @returns {Account|undefined} This tab's active account (whatever its status). */
  get active() { return this.get(this.#active); }
  get activeKey() { return this.#active; }

  /**
   * The identity `subjectMatches()` compares a security event's subject with: `iss`, `sub`, the grant's
   * session ids as `sid`, and a verified email or phone number.
   * @param {string} key
   * @returns {{ iss: string, sub: string, sid?: string[], email?: string, email_verified?: boolean,
   *   phone_number?: string, phone_number_verified?: boolean }|undefined}
   */
  identity(key) {
    const a = this.#accounts.get(key);
    return a && { iss: a.iss, sub: a.sub, sid: a.sessions, email: a.email, email_verified: a.email_verified,
      phone_number: a.phone_number, phone_number_verified: a.phone_number_verified };
  }

  /**
   * The accounts a security event's subject (`sub_id`) is about. A subject naming a session (iya-sts:
   * `gnap-grant:<id>` or `gnap-token:<jti>`) matches only the account holding that grant or token.
   * @param {object} subId
   * @returns {Account[]}
   */
  accountsForSubject(subId) {
    return this.list().filter((a) => subjectMatches(subId, this.identity(a.key)));
  }

  // ---------------------------------------------------------------------------
  // The active account's grant: the only one reachable
  // ---------------------------------------------------------------------------

  /**
   * The active account's grant, its token rotated first when (nearly) expired.
   * @param {{ forceRefresh?: boolean }} [opts]
   * @returns {Promise<GrantSet>}
   */
  getTokenSet(opts) {
    return this.#tokensFor(this.#active, opts);
  }

  /**
   * Rotates the active account's access token now.
   * @returns {Promise<GrantSet>}
   */
  rotate() {
    return this.#tokensFor(this.#active, { forceRefresh: true });
  }

  async #tokensFor(key, opts) {
    if (!key || (key !== this.#active && key !== this.#activating)) {
      throw new GNAPClientError('Only the active account\'s tokens can be used; activate the account first', { code: 'not_active' });
    }
    if (this.#accounts.get(key)?.status !== 'signed-in') {
      throw new GNAPClientError('The active account is not signed in', { code: 'no_tokens' });
    }
    return this.#tokens.getTokenSet(key, opts);
  }

  // ---------------------------------------------------------------------------
  // Signing in
  // ---------------------------------------------------------------------------

  /**
   * Starts a grant the AS decides on. Resolves `{ url }` to send the browser to; or, when the AS issued
   * the grant with nobody asked, the signed-in account (`{ account, grantSet, intent, added }`).
   * @param {Parameters<import('./gnap-client.js').GNAPClient['createGrantRequest']>[0]} [opts]
   */
  signIn(opts = {}) {
    return this.#start({ ...opts, context: { intent: 'sign-in' } });
  }

  /**
   * Starts a grant for another person, added as a further account.
   * @param {Parameters<import('./gnap-client.js').GNAPClient['createGrantRequest']>[0]} [opts]
   */
  addAccount(opts = {}) {
    return this.#start({ ...opts, context: { intent: 'add' } });
  }

  /**
   * Starts a grant for this account's person again: the request names them in `user` (RFC 9635 section
   * 2.4), and a grant approved by anybody else is refused at the callback (`account_mismatch`).
   * @param {string} key
   * @param {Parameters<import('./gnap-client.js').GNAPClient['createGrantRequest']>[0]} [opts]
   */
  reauthenticate(key, opts = {}) {
    const a = this.#mustGet(key);
    return this.#start({
      user: { sub_ids: [{ format: 'iss_sub', iss: a.iss, sub: a.sub }] },
      ...opts,
      expectedSub: a.sub,
      context: { intent: 'reauth', key },
    });
  }

  async #start(opts) {
    const result = await this.#client.createGrantRequest(opts);
    if (result.grantSet) return this.#record(result.grantSet, opts.context);
    return { url: /** @type {string} */ (result.url) };
  }

  /**
   * Completes a grant from the finish redirect. The person it is about is added to the cache (or, when
   * already listed, signed in again) and becomes this tab's active account.
   *
   * An error is thrown with `err.context` (`{ intent, key? }`) and, for `reauth`, `err.account`.
   * @param {URLSearchParams|Record<string,string>|string} response
   * @returns {Promise<{ account: Account, grantSet: GrantSet, intent: string, added: boolean }>}
   */
  async handleCallback(response) {
    let result;
    try {
      result = await this.#client.completeGrant(response);
    } catch (err) {
      if (err.context?.key) {
        await this.#load();
        err.account = this.get(err.context.key);
      }
      throw err;
    }
    return this.#record(result.grantSet, result.context);
  }

  async #record(grantSet, context) {
    const claims = grantSet.claims;
    if (!claims?.sub) {
      await this.#client.revokeGrant(grantSet).catch(() => {});
      throw new GNAPClientError('The grant carries no subject information, so nobody can be signed in: ask for sub_id formats the AS supports',
        { code: 'no_subject' });
    }
    const key = await accountKey(claims.iss, claims.sub);
    let added = false;
    await this.#mutate(async () => {
      let account = this.#accounts.get(key);
      added = !account;
      if (added) {
        this.#makeRoom(grantSet);
        account = /** @type {Account} */ ({ key, addedAt: Date.now() });
        this.#accounts.set(key, account);
      }
      for (const c of PROFILE_CLAIMS) delete account[c];
      Object.assign(account, pick(claims, PROFILE_CLAIMS), {
        status: 'signed-in', lastUsedAt: Date.now(), sessions: grantSet.sessionIds(), grantId: grantSet.grant_id,
      });
      delete account.endedReason;
      delete account.changedAt;
      await this.#tokens.set(key, grantSet, { schedule: false });
    });
    this.emit(added ? 'added' : 'updated', this.get(key));
    await this.#activate(key);
    return { account: /** @type {Account} */ (this.get(key)), grantSet, intent: context?.intent ?? 'sign-in', added };
  }

  // ---------------------------------------------------------------------------
  // Activating
  // ---------------------------------------------------------------------------

  /**
   * Makes a listed account this tab's active account; the previous one becomes dormant. Nothing is sent to
   * the AS unless the account's token is due for rotation. When the rotation or `onActivate` fails, the
   * previously active account is reactivated and the error thrown.
   * @param {string} key
   * @returns {Promise<Account|undefined>}
   */
  async activate(key) {
    this.#mustGet(key);
    const previous = this.#active;
    try {
      await this.#activate(key);
    } catch (err) {
      if (previous && previous !== key && this.#active !== previous) await this.#activate(previous).catch(() => {});
      throw err;
    }
    return this.active;
  }

  async #activate(key) {
    await this.#load();
    const previous = this.#active;
    if (previous && previous !== key) await this.#deactivate();
    this.#mustGet(key);
    if (this.#accounts.get(key).status === 'signed-in') {
      let ts = await this.#tokens.get(key);
      if (ts?.isExpired(this.#opts.refreshSkewSec)) {
        ts = ts.canRotate() ? await this.#tokens.rotate(key) : (ts.isExpired() ? undefined : ts);
      }
      if (!ts) {
        await this.#tokens.delete(key).catch(() => {});
        await this.#mutate(() => this.#setStatus(key, 'tokens-missing'));
      } else if (this.#opts.onActivate) {
        this.#activating = key;
        try {
          await this.#opts.onActivate(this.get(key), { getTokenSet: (opts) => this.#tokensFor(key, opts) });
        } finally {
          this.#activating = undefined;
        }
        await this.#load(); // a signal acted on during onActivate may have ended the account
      }
    }
    this.#active = key;
    await this.#tabStore.set(this.#tabKey(), key);
    if (this.#accounts.get(key)?.status === 'signed-in') {
      await this.#mutate(() => { const a = this.#accounts.get(key); if (a) a.lastUsedAt = Date.now(); });
      await this.#tokens.schedule(key);
    }
    if (previous !== key) this.emit('activated', this.get(key), this.get(previous));
    this.emit('change');
  }

  async #deactivate() {
    const key = this.#active;
    if (!key) return;
    this.#tokens.unschedule(key);
    this.#active = undefined;
    await this.#tabStore.delete(this.#tabKey());
    const a = this.get(key);
    if (a) await Promise.resolve(this.#opts.onDeactivate?.(a)).catch(() => {});
  }

  // ---------------------------------------------------------------------------
  // Signing out, ending, forgetting
  // ---------------------------------------------------------------------------

  /**
   * Signs one account out of this browser: `onLeave` runs, its grant is revoked at the AS (with `revoke`,
   * the default) and removed from the cache, and it stays listed as `signed-out`. GNAP has no front-channel
   * logout: revoking the grant is what ends it, and iya-sts then sends CAEP `session-revoked` for it.
   * @param {string} [key]  Default: the active account.
   * @param {{ revoke?: boolean }} [opts]
   * @returns {Promise<Account|undefined>}
   */
  async signOut(key = this.#active, { revoke = true } = {}) {
    if (!key) return undefined;
    const { account } = await this.#leave(key, 'signed-out', { revoke });
    await this.#afterLeaving(key);
    this.emit('signed-out', account);
    this.emit('change');
    return this.get(key);
  }

  /**
   * Signs every account out of this browser, revoking each grant.
   * @param {{ revoke?: boolean }} [opts]
   */
  async signOutAll({ revoke = true } = {}) {
    await this.#load();
    const previous = this.active;
    for (const a of this.list().filter((x) => x.status === 'signed-in' || x.status === 'tokens-missing')) {
      const { account } = await this.#leave(a.key, 'signed-out', { revoke });
      this.emit('signed-out', account);
    }
    if (this.#active) await this.#deactivate();
    if (previous) this.emit('activated', undefined, this.get(previous.key));
    this.emit('change');
  }

  /**
   * Ends an account's session in this browser because the AS or a security event says its grant has
   * ended: `onLeave` runs, its grant is removed from the cache (not revoked: the AS already knows), and it
   * stays listed as `ended` with the reason. Does nothing for an account that is not signed in.
   * @param {string} key
   * @param {string} [reason]
   * @returns {Promise<Account|undefined>}
   */
  async end(key, reason) {
    await this.#load();
    const a = this.#accounts.get(key);
    if (!a || (a.status !== 'signed-in' && a.status !== 'tokens-missing')) return a && { ...a };
    const { account } = await this.#leave(key, 'ended', { revoke: false, reason });
    if (this.#activating !== key) await this.#afterLeaving(key);
    this.emit('ended', account, reason);
    this.emit('change');
    return this.get(key);
  }

  /**
   * Removes an account that is not signed in from the list.
   * @param {string} key
   * @returns {Promise<void>}
   */
  async forget(key) {
    let removed;
    await this.#mutate(() => {
      const a = this.#mustGet(key);
      if (a.status === 'signed-in') throw new GNAPClientError('Sign the account out before forgetting it', { code: 'account_signed_in' });
      this.#accounts.delete(key);
      removed = a;
    });
    await this.#tokens.delete(key).catch(() => {});
    if (this.#active === key) {
      this.#active = undefined;
      await this.#tabStore.delete(this.#tabKey());
      this.emit('activated', undefined, removed);
    }
    this.emit('forgotten', removed);
    this.emit('change');
  }

  /** Cancels rotation timers and stops listening to other tabs (call on shutdown). */
  close() {
    this.#tokens.close();
    this.#channel?.close();
  }

  // ---------------------------------------------------------------------------
  // Internals
  // ---------------------------------------------------------------------------

  #tabKey() { return `active:${this.#storeKey}`; }

  #mustGet(key) {
    const a = this.#accounts.get(key);
    if (!a) throw new GNAPClientError(`No account ${key}`, { code: 'no_account' });
    return a;
  }

  async #leave(key, status, { revoke, reason }) {
    await this.#load();
    const a = this.#mustGet(key);
    const cached = await this.#tokens.get(key);
    if (cached && this.#opts.onLeave) {
      await Promise.resolve(this.#opts.onLeave(this.get(key), { getTokenSet: (opts) => this.#tokens.getTokenSet(key, opts) })).catch(() => {});
    }
    await this.#tokens.delete(key, { revoke }).catch(() => {});
    await this.#mutate(() => {
      this.#setStatus(key, status);
      const x = this.#accounts.get(key);
      if (x && reason !== undefined) x.endedReason = reason;
    });
    return { account: this.get(key) ?? { ...a, status } };
  }

  async #afterLeaving(key) {
    if (this.#active !== key) return;
    await this.#deactivate();
    const next = [...this.#accounts.values()].filter((a) => a.status === 'signed-in').sort((a, b) => b.addedAt - a.addedAt)[0];
    if (next) {
      await this.#activate(next.key).catch((err) => this.emit('activation_error', this.get(next.key), err));
    } else {
      this.emit('activated', undefined, this.get(key));
    }
  }

  #setStatus(key, status) {
    const a = this.#accounts.get(key);
    if (!a) return;
    a.status = status;
    a.changedAt = Date.now();
    if (status !== 'ended') delete a.endedReason;
  }

  #makeRoom(grantSet) {
    if (this.#accounts.size < this.#opts.maxAccounts) return;
    const droppable = [...this.#accounts.values()].filter((a) => a.status !== 'signed-in')
      .sort((a, b) => (a.changedAt ?? a.lastUsedAt) - (b.changedAt ?? b.lastUsedAt));
    if (!droppable.length) {
      void this.#client.revokeGrant(grantSet).catch(() => {});
      throw new GNAPClientError(`${this.#opts.maxAccounts} accounts are signed in already; sign one out first`, { code: 'too_many_accounts' });
    }
    this.#accounts.delete(droppable[0].key);
    this.#tokens.delete(droppable[0].key).catch(() => {});
    this.emit('forgotten', droppable[0]);
  }

  async #onRotated(key, ts) {
    await this.#mutate(() => {
      const a = this.#accounts.get(key);
      if (a) a.sessions = GrantSet.from(ts).sessionIds();
    });
    if (key === this.#active) this.emit('rotated', this.get(key));
    this.emit('change');
  }

  async #onRemoteChange() {
    await this.#load();
    const key = this.#active;
    if (key && this.#accounts.get(key)?.status !== 'signed-in') this.#tokens.unschedule(key);
    if (key && !this.#accounts.has(key)) {
      this.#active = undefined;
      await this.#tabStore.delete(this.#tabKey());
      this.emit('activated', undefined, undefined);
    }
    this.emit('change');
  }

  /** Re-reads the shared list, after any change this tab is making. Never call it inside a #mutate callback. */
  async #load() {
    while (this.#mutating) await this.#mutating.catch(() => {});
    await this.#read();
  }

  async #read() {
    const saved = await this.#store.get(this.#storeKey);
    this.#accounts = new Map((saved?.accounts ?? []).map((a) => [a.key, a]));
  }

  /** Read-modify-write of the shared list, under a lock shared by the tabs; then tells the other tabs. */
  async #mutate(fn) {
    while (this.#mutating) await this.#mutating.catch(() => {});
    const run = withLock(`gnap-caep-client:${this.#storeKey}`, async () => {
      await this.#read();
      await fn();
      await this.#store.set(this.#storeKey, { accounts: [...this.#accounts.values()] });
    });
    this.#mutating = run;
    try {
      await run;
    } finally {
      if (this.#mutating === run) this.#mutating = undefined;
    }
    this.#channel?.postMessage({ type: 'change' });
  }
}

/**
 * The account key for an `iss` and `sub`: stable, opaque, and safe in a storage key or a URL.
 * @param {string} iss
 * @param {string} sub
 * @returns {Promise<string>}
 */
export async function accountKey(iss, sub) {
  return `acct-${base64url(await digest(`${iss}\n${sub}`)).slice(0, 22)}`;
}

function pick(obj, keys) {
  const out = {};
  for (const k of keys) if (obj[k] !== undefined) out[k] = obj[k];
  return out;
}