@ascencia/id-core 0.1.0-rc.1

package/src/client.ts

@@ -0,0 +1,657 @@
+/**
+ * `AscenciaClient` : le flux `authorization_code` + PKCE, de bout en bout, sans
+ * la moindre dépendance ni le moindre appel au DOM.
+ *
+ * Ce qui est **volontairement absent** : la popup, l'overlay, le `postMessage`
+ * et le repli redirection (docs/04-AUTH-FLOWS.md §7). Cette classe fabrique
+ * l'URL d'autorisation et consomme le retour ; qui navigue, et comment, est la
+ * responsabilité du widget ou du SDK de framework.
+ */
+
+import { evaluate } from '@ascencia/id-rbac';
+import { DEFAULT_DISCOVERY_TTL_MS, discover, normalizeIssuer } from './discovery';
+import { AscenciaError, toAscenciaError } from './errors';
+import { CODE_CHALLENGE_METHOD, challengeFromVerifier, generateNonce, generateState, generateVerifier } from './pkce';
+import { resolveStorage } from './storage';
+import type {
+  AscenciaConfig,
+  AscenciaEventHandler,
+  AscenciaEventMap,
+  AscenciaEventName,
+  AuthContext,
+  AuthorizeRequest,
+  CallbackInput,
+  CallbackParams,
+  CallbackResult,
+  DiscoveryDocument,
+  FetchLike,
+  SignInOptions,
+  SignOutOptions,
+  StorageAdapter,
+  Tokens,
+  Unsubscribe,
+  User,
+} from './types';
+
+const DEFAULT_SCOPES = ['openid', 'profile', 'email', 'ascencia.roles'];
+const DEFAULT_SKEW_SECONDS = 60;
+const DEFAULT_CONTEXT_TTL_MS = 60_000;
+
+/** Même TTL que le `state` côté serveur (docs/04-AUTH-FLOWS.md §7). */
+const TRANSACTION_TTL_MS = 600_000;
+
+/** Ce qu'on garde entre l'appel à `/oauth/authorize` et le retour sur le `redirect_uri`. */
+interface Transaction {
+  state: string;
+  verifier: string;
+  nonce: string;
+  redirectUri: string;
+  createdAt: number;
+}
+
+interface TokenEndpointResponse {
+  access_token?: unknown;
+  token_type?: unknown;
+  expires_in?: unknown;
+  refresh_token?: unknown;
+  id_token?: unknown;
+  scope?: unknown;
+  error?: unknown;
+  error_description?: unknown;
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+/**
+ * Traduit les claims OIDC standard vers la forme exposée aux développeurs.
+ * `/oauth/userinfo` parle `name`/`picture`, le reste du produit parle
+ * `display_name`/`avatar_url`.
+ */
+function userFromClaims(claims: Record<string, unknown>): User {
+  return {
+    id: asString(claims.sub) ?? '',
+    email: asString(claims.email),
+    email_verified: claims.email_verified === true,
+    display_name: asString(claims.name),
+    username: asString(claims.preferred_username),
+    avatar_url: asString(claims.picture),
+    locale: asString(claims.locale),
+  };
+}
+
+function parseCallback(input: CallbackInput): CallbackParams {
+  if (typeof input === 'string' || input instanceof URL) {
+    const url = typeof input === 'string' ? new URL(input, 'http://localhost') : input;
+    // `response_mode=fragment` place les paramètres après le `#`, pas après le `?`.
+    const fragment = new URLSearchParams(url.hash.replace(/^#/, ''));
+    const query = url.searchParams;
+    const pick = (key: string) => query.get(key) ?? fragment.get(key);
+    return {
+      code: pick('code'),
+      state: pick('state'),
+      error: pick('error'),
+      error_description: pick('error_description'),
+    };
+  }
+
+  if (input instanceof URLSearchParams) {
+    return {
+      code: input.get('code'),
+      state: input.get('state'),
+      error: input.get('error'),
+      error_description: input.get('error_description'),
+    };
+  }
+
+  return input;
+}
+
+export class AscenciaClient {
+  readonly issuer: string;
+
+  readonly #config: AscenciaConfig;
+  readonly #fetch: FetchLike;
+  readonly #tokenStore: StorageAdapter;
+  readonly #transactionStore: StorageAdapter;
+  readonly #prefix: string;
+  readonly #skewMs: number;
+  readonly #listeners = new Map<AscenciaEventName, Set<(...args: never[]) => void>>();
+
+  #tokens: Tokens | null = null;
+  #user: User | null = null;
+  #context: AuthContext | null = null;
+  #contextFetchedAt = 0;
+  #refreshing: Promise<Tokens> | null = null;
+
+  constructor(config: AscenciaConfig) {
+    if (!config.issuer) throw new AscenciaError('invalid_config', '`issuer` est obligatoire.');
+    if (!config.clientId) throw new AscenciaError('invalid_config', '`clientId` est obligatoire.');
+    if (!config.redirectUri) {
+      throw new AscenciaError('invalid_config', '`redirectUri` est obligatoire.');
+    }
+
+    this.#config = config;
+    this.issuer = normalizeIssuer(config.issuer);
+    this.#prefix = config.storagePrefix ?? 'ascencia';
+    this.#skewMs = (config.clockSkewSeconds ?? DEFAULT_SKEW_SECONDS) * 1000;
+
+    const provided = config.fetch;
+    // Sans `bind`, `fetch` détaché du global lève une « Illegal invocation ».
+    this.#fetch = provided ?? ((input, init) => globalThis.fetch(input, init));
+
+    // Les jetons restent en mémoire tant que le développeur n'a pas choisi
+    // autre chose ; la transaction PKCE, elle, doit survivre à une navigation
+    // complète, sinon le repli redirection est impossible.
+    this.#tokenStore = resolveStorage(config.storage, 'memory');
+    this.#transactionStore = resolveStorage(config.transactionStorage, 'session');
+
+    this.#tokens = this.#restoreTokens();
+  }
+
+  // ── Événements ─────────────────────────────────────────────────────────────
+
+  on<E extends AscenciaEventName>(event: E, handler: AscenciaEventHandler<E>): Unsubscribe {
+    let set = this.#listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.#listeners.set(event, set);
+    }
+    set.add(handler as (...args: never[]) => void);
+    return () => this.off(event, handler);
+  }
+
+  off<E extends AscenciaEventName>(event: E, handler: AscenciaEventHandler<E>): void {
+    this.#listeners.get(event)?.delete(handler as (...args: never[]) => void);
+  }
+
+  #emit<E extends AscenciaEventName>(event: E, ...args: AscenciaEventMap[E]): void {
+    for (const handler of this.#listeners.get(event) ?? []) {
+      try {
+        (handler as AscenciaEventHandler<E>)(...args);
+      } catch {
+        // Un abonné qui plante ne doit ni interrompre les suivants ni faire
+        // échouer l'opération qui a déclenché l'événement.
+      }
+    }
+  }
+
+  // ── Métadonnées ────────────────────────────────────────────────────────────
+
+  async metadata(): Promise<DiscoveryDocument> {
+    if (this.#config.metadata) return this.#config.metadata;
+    return discover(this.issuer, {
+      fetch: this.#fetch,
+      ttlMs: this.#config.discoveryTtlMs ?? DEFAULT_DISCOVERY_TTL_MS,
+    });
+  }
+
+  // ── Autorisation ───────────────────────────────────────────────────────────
+
+  async buildAuthorizeUrl(options: SignInOptions = {}): Promise<AuthorizeRequest> {
+    const metadata = await this.metadata();
+
+    const state = generateState();
+    const nonce = generateNonce();
+    const verifier = generateVerifier();
+    const challenge = await challengeFromVerifier(verifier);
+    const redirectUri = options.redirectUri ?? this.#config.redirectUri;
+
+    const url = new URL(metadata.authorization_endpoint);
+    const params = url.searchParams;
+    params.set('response_type', 'code');
+    params.set('client_id', this.#config.clientId);
+    params.set('redirect_uri', redirectUri);
+    params.set('scope', (options.scopes ?? this.#config.scopes ?? DEFAULT_SCOPES).join(' '));
+    params.set('state', state);
+    params.set('nonce', nonce);
+    params.set('code_challenge', challenge);
+    params.set('code_challenge_method', CODE_CHALLENGE_METHOD);
+
+    // `screen: 'register'` est du vocabulaire produit ; sur le fil, c'est le
+    // `prompt=create` d'OIDC. Un `prompt` explicite reste prioritaire.
+    const prompt = options.prompt ?? (options.screen === 'register' ? 'create' : undefined);
+    if (prompt) params.set('prompt', prompt);
+
+    if (options.provider) params.set('provider', options.provider);
+    if (options.loginHint) params.set('login_hint', options.loginHint);
+    if (options.uiLocales) params.set('ui_locales', options.uiLocales);
+    if (options.acrValues) params.set('acr_values', options.acrValues);
+    if (options.maxAge !== undefined) params.set('max_age', String(options.maxAge));
+    if (options.responseMode) params.set('response_mode', options.responseMode);
+    if (this.#config.app) params.set('app', this.#config.app);
+
+    for (const [key, value] of Object.entries(options.extraParams ?? {})) {
+      params.set(key, value);
+    }
+
+    this.#saveTransaction({ state, verifier, nonce, redirectUri, createdAt: Date.now() });
+
+    return {
+      url: url.toString(),
+      state,
+      nonce,
+      codeVerifier: verifier,
+      codeChallenge: challenge,
+      redirectUri,
+    };
+  }
+
+  /**
+   * Consomme le retour d'autorisation : vérifie le `state`, échange le code,
+   * charge le profil. Par défaut, lit `location.href`.
+   */
+  async handleCallback(input?: CallbackInput): Promise<CallbackResult> {
+    const source = input ?? globalThis.location?.href;
+    if (source === undefined) {
+      throw this.#fail(
+        new AscenciaError('invalid_request', "Aucune URL de retour : passez-la explicitement à handleCallback()."),
+      );
+    }
+
+    const params = parseCallback(source);
+
+    if (params.error) {
+      throw this.#fail(
+        new AscenciaError(params.error, params.error_description ?? params.error, {
+          description: params.error_description ?? null,
+        }),
+      );
+    }
+
+    if (!params.state) {
+      throw this.#fail(
+        new AscenciaError('invalid_state', 'Le paramètre `state` est absent du retour.'),
+      );
+    }
+
+    // Lecture ET suppression avant tout échange : le `state` est à usage
+    // unique, un rejeu de la même URL de retour doit échouer même si le
+    // premier passage a planté plus loin.
+    const transaction = this.#takeTransaction(params.state);
+    if (!transaction) {
+      throw this.#fail(
+        new AscenciaError(
+          'invalid_state',
+          "Le `state` reçu ne correspond à aucune demande d'autorisation en cours.",
+        ),
+      );
+    }
+
+    if (transaction.state !== params.state) {
+      throw this.#fail(new AscenciaError('invalid_state', 'Le `state` reçu ne correspond pas.'));
+    }
+
+    if (Date.now() - transaction.createdAt > TRANSACTION_TTL_MS) {
+      throw this.#fail(
+        new AscenciaError('state_expired', "La demande d'autorisation a expiré (10 min)."),
+      );
+    }
+
+    if (!params.code) {
+      throw this.#fail(new AscenciaError('invalid_request', 'Le paramètre `code` est absent.'));
+    }
+
+    const tokens = await this.exchangeCode(params.code, transaction.verifier, transaction.redirectUri);
+
+    const user = (await this.getUser({ force: true })) ?? {
+      id: '',
+      email: null,
+      email_verified: false,
+      display_name: null,
+      username: null,
+      avatar_url: null,
+      locale: null,
+    };
+
+    this.#emit('signin', user);
+    return { tokens, user };
+  }
+
+  async exchangeCode(code: string, codeVerifier: string, redirectUri?: string): Promise<Tokens> {
+    const tokens = await this.#postToken({
+      grant_type: 'authorization_code',
+      code,
+      code_verifier: codeVerifier,
+      redirect_uri: redirectUri ?? this.#config.redirectUri,
+    });
+
+    this.#storeTokens(tokens);
+    return tokens;
+  }
+
+  // ── Jetons ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Les appels concurrents partagent un unique aller-retour : trois composants
+   * qui demandent le jeton au même instant après une expiration ne doivent pas
+   * produire trois rotations de refresh token, ce que l'IdP prendrait pour un
+   * rejeu et sanctionnerait en révoquant toute la famille.
+   */
+  async refresh(): Promise<Tokens> {
+    if (this.#refreshing) return this.#refreshing;
+
+    const pending = this.#performRefresh();
+    this.#refreshing = pending;
+
+    const release = () => {
+      if (this.#refreshing === pending) this.#refreshing = null;
+    };
+    pending.then(release, release);
+
+    return pending;
+  }
+
+  async #performRefresh(): Promise<Tokens> {
+    const refreshToken = this.#tokens?.refreshToken ?? this.#tokenStore.get(this.#refreshKey());
+    if (!refreshToken) {
+      throw new AscenciaError(
+        'no_refresh_token',
+        "Aucun refresh token disponible. Les clients publics qui laissent l'IdP gérer le cookie `__Host` doivent repasser par une autorisation.",
+      );
+    }
+
+    const tokens = await this.#postToken({
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+    });
+
+    this.#storeTokens(tokens);
+    this.#emit('refresh', tokens);
+    return tokens;
+  }
+
+  /** `null` si personne n'est connecté ou si le renouvellement a échoué. */
+  async getAccessToken(): Promise<string | null> {
+    if (this.#tokens && !this.#isExpired(this.#tokens)) return this.#tokens.accessToken;
+
+    const hasRefresh = Boolean(this.#tokens?.refreshToken ?? this.#tokenStore.get(this.#refreshKey()));
+    if (!hasRefresh) return null;
+
+    try {
+      return (await this.refresh()).accessToken;
+    } catch (cause) {
+      // Un refresh refusé signifie que la session est morte côté serveur :
+      // on nettoie plutôt que de laisser l'application boucler sur un 401.
+      this.#emit('error', toAscenciaError(cause, 'refresh_failed'));
+      this.#clearSession();
+      this.#emit('signout');
+      return null;
+    }
+  }
+
+  getTokens(): Tokens | null {
+    return this.#tokens;
+  }
+
+  isAuthenticated(): boolean {
+    if (!this.#tokens) return false;
+    return !this.#isExpired(this.#tokens) || Boolean(this.#tokens.refreshToken);
+  }
+
+  // ── Profil et droits ───────────────────────────────────────────────────────
+
+  async getUser(options: { force?: boolean } = {}): Promise<User | null> {
+    if (this.#user && !options.force) return this.#user;
+
+    const metadata = await this.metadata();
+    const endpoint = metadata.userinfo_endpoint ?? `${this.issuer}/oauth/userinfo`;
+
+    const claims = await this.#authorizedJson<Record<string, unknown>>(endpoint);
+    if (!claims) return null;
+
+    this.#user = userFromClaims(claims);
+    return this.#user;
+  }
+
+  /**
+   * `GET /api/v1/me/context` : profil, rôles et permissions en une requête.
+   * Le cache court évite qu'un rendu qui appelle `can()` dix fois déclenche dix
+   * allers-retours ; l'invalidation immédiate passe par le webhook
+   * `roles.changed` côté application (docs/05-API.md §3).
+   */
+  async getContext(options: { force?: boolean } = {}): Promise<AuthContext | null> {
+    const ttl = this.#config.contextTtlMs ?? DEFAULT_CONTEXT_TTL_MS;
+    if (this.#context && !options.force && Date.now() - this.#contextFetchedAt < ttl) {
+      return this.#context;
+    }
+
+    const url = new URL(`${this.issuer}/api/v1/me/context`);
+    if (this.#config.app) url.searchParams.set('app', this.#config.app);
+
+    const context = await this.#authorizedJson<AuthContext>(url.toString());
+    if (!context) return null;
+
+    this.#context = context;
+    this.#contextFetchedAt = Date.now();
+    if (context.account) this.#user = context.account;
+    return context;
+  }
+
+  /**
+   * Synchrone et purement locale : elle répond depuis le dernier contexte
+   * chargé. Une vérification qui engage quelque chose se fait côté serveur.
+   */
+  can(permission: string): boolean {
+    const context = this.#context;
+    if (!context) return false;
+    return evaluate({ allow: context.permissions, deny: context.denied }, permission);
+  }
+
+  hasRole(key: string): boolean {
+    const context = this.#context;
+    if (!context) return false;
+    return context.roles.some((role) => role.key === key) || context.platform_roles.includes(key);
+  }
+
+  getCachedContext(): AuthContext | null {
+    return this.#context;
+  }
+
+  // ── Déconnexion ────────────────────────────────────────────────────────────
+
+  /**
+   * Renvoie l'URL de fin de session quand `global` est demandé, `null` sinon.
+   *
+   * Le refresh token n'est pas révoqué au passage : `/oauth/revoke` exige une
+   * authentification de client, dont un client public ne dispose pas. La
+   * déconnexion globale, elle, coupe la session côté IdP.
+   */
+  async signOut(options: SignOutOptions = {}): Promise<string | null> {
+    const idToken = this.#tokens?.idToken ?? null;
+
+    this.#clearSession();
+    this.#emit('signout');
+
+    if (!options.global) return null;
+
+    const metadata = await this.metadata();
+    const endpoint = metadata.end_session_endpoint ?? `${this.issuer}/oauth/logout`;
+    const url = new URL(endpoint);
+    if (idToken) url.searchParams.set('id_token_hint', idToken);
+
+    const postLogout = options.postLogoutRedirectUri;
+    if (postLogout) url.searchParams.set('post_logout_redirect_uri', postLogout);
+
+    const target = url.toString();
+    const shouldRedirect = options.redirect ?? true;
+    if (shouldRedirect) globalThis.location?.assign(target);
+
+    return target;
+  }
+
+  // ── Interne ────────────────────────────────────────────────────────────────
+
+  #isExpired(tokens: Tokens): boolean {
+    return Date.now() >= tokens.expiresAt - this.#skewMs;
+  }
+
+  #refreshKey(): string {
+    return `${this.#prefix}:rt`;
+  }
+
+  #transactionKey(state: string): string {
+    return `${this.#prefix}:tx:${state}`;
+  }
+
+  #saveTransaction(transaction: Transaction): void {
+    this.#transactionStore.set(this.#transactionKey(transaction.state), JSON.stringify(transaction));
+  }
+
+  #takeTransaction(state: string): Transaction | null {
+    const key = this.#transactionKey(state);
+    const raw = this.#transactionStore.get(key);
+    this.#transactionStore.remove(key);
+    if (!raw) return null;
+
+    try {
+      const parsed = JSON.parse(raw) as Transaction;
+      if (typeof parsed.state !== 'string' || typeof parsed.verifier !== 'string') return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+
+  #restoreTokens(): Tokens | null {
+    // Seul le refresh token est éventuellement persisté : l'access token reste
+    // en mémoire, où un XSS doit au moins travailler pour aller le chercher.
+    const refreshToken = this.#tokenStore.get(this.#refreshKey());
+    if (!refreshToken) return null;
+    return {
+      accessToken: '',
+      tokenType: 'Bearer',
+      expiresAt: 0,
+      refreshToken,
+      idToken: null,
+      scope: [],
+    };
+  }
+
+  #storeTokens(tokens: Tokens): void {
+    this.#tokens = tokens;
+    // Le contexte dépend des droits du porteur : un nouveau jeton peut porter
+    // de nouveaux rôles.
+    this.#context = null;
+    this.#contextFetchedAt = 0;
+
+    if (tokens.refreshToken) {
+      this.#tokenStore.set(this.#refreshKey(), tokens.refreshToken);
+    } else {
+      this.#tokenStore.remove(this.#refreshKey());
+    }
+  }
+
+  #clearSession(): void {
+    this.#tokens = null;
+    this.#user = null;
+    this.#context = null;
+    this.#contextFetchedAt = 0;
+    this.#tokenStore.remove(this.#refreshKey());
+  }
+
+  /** Émet `error` avant de rendre l'erreur, pour que les abonnés la voient aussi. */
+  #fail(error: AscenciaError): AscenciaError {
+    this.#emit('error', error);
+    return error;
+  }
+
+  async #postToken(fields: Record<string, string>): Promise<Tokens> {
+    const metadata = await this.metadata();
+
+    const body = new URLSearchParams(fields);
+    body.set('client_id', this.#config.clientId);
+    // `client_secret_post` plutôt que Basic : pas de base64 à fabriquer, et le
+    // serveur accepte les deux (apps/id/src/lib/oauth/clients.ts).
+    if (this.#config.clientSecret) body.set('client_secret', this.#config.clientSecret);
+
+    let response: Response;
+    try {
+      response = await this.#fetch(metadata.token_endpoint, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/x-www-form-urlencoded',
+          accept: 'application/json',
+        },
+        body: body.toString(),
+      });
+    } catch (cause) {
+      throw this.#fail(
+        new AscenciaError('network_error', "Le point d'accès jeton est injoignable.", { cause }),
+      );
+    }
+
+    let payload: TokenEndpointResponse = {};
+    try {
+      payload = (await response.json()) as TokenEndpointResponse;
+    } catch {
+      // Un 204 ou une réponse tronquée : le contrôle de statut ci-dessous
+      // produira un message plus utile qu'une erreur de parsing.
+    }
+
+    if (!response.ok || payload.error) {
+      const code = asString(payload.error) ?? 'token_request_failed';
+      const description = asString(payload.error_description);
+      throw this.#fail(
+        new AscenciaError(code, description ?? `Échec de la requête jeton (${response.status}).`, {
+          description,
+          status: response.status,
+        }),
+      );
+    }
+
+    const accessToken = asString(payload.access_token);
+    if (!accessToken) {
+      throw this.#fail(
+        new AscenciaError('invalid_token_response', "La réponse ne contient pas d'access_token."),
+      );
+    }
+
+    const expiresIn = typeof payload.expires_in === 'number' ? payload.expires_in : 600;
+
+    return {
+      accessToken,
+      tokenType: asString(payload.token_type) ?? 'Bearer',
+      expiresAt: Date.now() + expiresIn * 1000,
+      refreshToken: asString(payload.refresh_token),
+      idToken: asString(payload.id_token),
+      scope: asString(payload.scope)?.split(' ').filter(Boolean) ?? [],
+    };
+  }
+
+  /** `null` quand il n'y a pas de jeton, ou quand l'IdP répond 401 / 403. */
+  async #authorizedJson<T>(url: string): Promise<T | null> {
+    const accessToken = await this.getAccessToken();
+    if (!accessToken) return null;
+
+    let response: Response;
+    try {
+      response = await this.#fetch(url, {
+        headers: { authorization: `Bearer ${accessToken}`, accept: 'application/json' },
+      });
+    } catch (cause) {
+      throw this.#fail(new AscenciaError('network_error', `${url} est injoignable.`, { cause }));
+    }
+
+    if (response.status === 401 || response.status === 403) return null;
+
+    if (!response.ok) {
+      throw this.#fail(
+        new AscenciaError('request_failed', `${url} a répondu ${response.status}.`, {
+          status: response.status,
+        }),
+      );
+    }
+
+    try {
+      return (await response.json()) as T;
+    } catch (cause) {
+      throw this.#fail(new AscenciaError('invalid_response', `Réponse illisible de ${url}.`, { cause }));
+    }
+  }
+}
+
+export function createClient(config: AscenciaConfig): AscenciaClient {
+  return new AscenciaClient(config);
+}