@ascencia/id-core 0.1.0-rc.1

package/src/discovery.ts

@@ -0,0 +1,170 @@
+/**
+ * Découverte OIDC.
+ *
+ * Le document est mis en cache par issuer, au niveau du module et non de
+ * l'instance : plusieurs `AscenciaClient` sur la même page (cas du widget
+ * cohabitant avec un SDK) ne doivent pas déclencher plusieurs requêtes.
+ *
+ * Voir docs/05-API.md §1.
+ */
+
+import { AscenciaError } from './errors';
+import type { DiscoveryDocument, FetchLike } from './types';
+
+/** Le serveur annonce `Cache-Control: max-age=3600` : on s'aligne dessus. */
+export const DEFAULT_DISCOVERY_TTL_MS = 3_600_000;
+
+export const DISCOVERY_PATH = '/.well-known/openid-configuration';
+
+interface CacheEntry {
+  expiresAt: number;
+  document: DiscoveryDocument;
+}
+
+const cache = new Map<string, CacheEntry>();
+const inFlight = new Map<string, Promise<DiscoveryDocument>>();
+
+/** Le slash final est signifiant dans une comparaison d'issuer : on l'enlève partout. */
+export function normalizeIssuer(issuer: string): string {
+  return issuer.replace(/\/+$/, '');
+}
+
+export function discoveryUrl(issuer: string): string {
+  return `${normalizeIssuer(issuer)}${DISCOVERY_PATH}`;
+}
+
+export interface DiscoverOptions {
+  fetch?: FetchLike;
+  ttlMs?: number;
+  /** Ignore le cache et refait la requête. */
+  force?: boolean;
+  signal?: AbortSignal;
+}
+
+function assertUsable(issuer: string, value: unknown): DiscoveryDocument {
+  if (typeof value !== 'object' || value === null) {
+    throw new AscenciaError('invalid_discovery', "Le document de découverte n'est pas un objet.");
+  }
+
+  const document = value as DiscoveryDocument;
+
+  // Contre-mesure au « mix-up » (RFC 8414 §3.3) : un document servi par un
+  // hôte détourné pointerait ses endpoints ailleurs tout en gardant l'air
+  // légitime. L'issuer annoncé doit être exactement celui qu'on a demandé.
+  if (normalizeIssuer(String(document.issuer ?? '')) !== issuer) {
+    throw new AscenciaError(
+      'issuer_mismatch',
+      `Le document annonce l'issuer « ${String(document.issuer)} » alors que « ${issuer} » était attendu.`,
+    );
+  }
+
+  for (const field of ['authorization_endpoint', 'token_endpoint'] as const) {
+    if (typeof document[field] !== 'string' || document[field].length === 0) {
+      throw new AscenciaError('invalid_discovery', `Le document ne déclare pas \`${field}\`.`);
+    }
+  }
+
+  const methods = document.code_challenge_methods_supported;
+  if (Array.isArray(methods) && !methods.includes('S256')) {
+    throw new AscenciaError(
+      'pkce_unsupported',
+      "Le serveur n'annonce pas `S256`. Ce client refuse de se rabattre sur `plain`.",
+    );
+  }
+
+  return document;
+}
+
+export async function discover(
+  issuer: string,
+  options: DiscoverOptions = {},
+): Promise<DiscoveryDocument> {
+  const key = normalizeIssuer(issuer);
+  const now = Date.now();
+
+  if (!options.force) {
+    const hit = cache.get(key);
+    if (hit && hit.expiresAt > now) return hit.document;
+
+    // Deux composants montés en même temps demandent le document au même
+    // instant : ils partagent la requête au lieu d'en lancer deux.
+    const pending = inFlight.get(key);
+    if (pending) return pending;
+  }
+
+  const request = fetchDocument(key, options)
+    .then((document) => {
+      cache.set(key, {
+        document,
+        expiresAt: Date.now() + (options.ttlMs ?? DEFAULT_DISCOVERY_TTL_MS),
+      });
+      return document;
+    })
+    .finally(() => {
+      inFlight.delete(key);
+    });
+
+  inFlight.set(key, request);
+  return request;
+}
+
+async function fetchDocument(issuer: string, options: DiscoverOptions): Promise<DiscoveryDocument> {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  if (typeof doFetch !== 'function') {
+    throw new AscenciaError('fetch_unavailable', '`fetch` est indisponible dans cet environnement.');
+  }
+
+  let response: Response;
+  try {
+    response = await doFetch(discoveryUrl(issuer), {
+      headers: { accept: 'application/json' },
+      ...(options.signal ? { signal: options.signal } : {}),
+    });
+  } catch (cause) {
+    throw new AscenciaError('network_error', `Découverte OIDC injoignable sur ${issuer}.`, {
+      cause,
+    });
+  }
+
+  if (!response.ok) {
+    throw new AscenciaError(
+      'discovery_failed',
+      `La découverte OIDC a répondu ${response.status}.`,
+      { status: response.status },
+    );
+  }
+
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch (cause) {
+    throw new AscenciaError('invalid_discovery', 'Réponse de découverte illisible.', { cause });
+  }
+
+  return assertUsable(issuer, body);
+}
+
+/** Sans argument, vide tout le cache. Sert aux tests et au changement d'issuer. */
+export function clearDiscoveryCache(issuer?: string): void {
+  if (issuer === undefined) {
+    cache.clear();
+    inFlight.clear();
+    return;
+  }
+  const key = normalizeIssuer(issuer);
+  cache.delete(key);
+  inFlight.delete(key);
+}
+
+/**
+ * Alimente le cache sans requête réseau. Permet à un rendu serveur de passer
+ * le document au client, et aux tests de se passer de `fetch`.
+ */
+export function seedDiscoveryCache(
+  issuer: string,
+  document: DiscoveryDocument,
+  ttlMs = DEFAULT_DISCOVERY_TTL_MS,
+): void {
+  const key = normalizeIssuer(issuer);
+  cache.set(key, { document: assertUsable(key, document), expiresAt: Date.now() + ttlMs });
+}

package/src/errors.ts

@@ -0,0 +1,32 @@
+/**
+ * Un seul type d'erreur pour tout le SDK : l'application n'a qu'un `catch` à
+ * écrire, et le `code` reste stable même si le message change de formulation
+ * ou de langue.
+ */
+export class AscenciaError extends Error {
+  /** Code machine : `invalid_state`, `network_error`, un code OAuth du serveur… */
+  readonly code: string;
+  /** `error_description` renvoyée par l'IdP, quand il y en a une. */
+  readonly description: string | null;
+  /** Statut HTTP à l'origine de l'erreur, `null` si elle est purement locale. */
+  readonly status: number | null;
+
+  constructor(
+    code: string,
+    message: string,
+    options: { description?: string | null; status?: number | null; cause?: unknown } = {},
+  ) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = 'AscenciaError';
+    this.code = code;
+    this.description = options.description ?? null;
+    this.status = options.status ?? null;
+  }
+}
+
+/** Normalise n'importe quoi de jeté en `AscenciaError`, sans perdre l'original. */
+export function toAscenciaError(value: unknown, fallbackCode = 'unknown_error'): AscenciaError {
+  if (value instanceof AscenciaError) return value;
+  const message = value instanceof Error ? value.message : String(value);
+  return new AscenciaError(fallbackCode, message, { cause: value });
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+export * from './types';
+export { AscenciaError, toAscenciaError } from './errors';
+export {
+  CODE_CHALLENGE_METHOD,
+  base64UrlEncode,
+  challengeFromVerifier,
+  generateNonce,
+  generateState,
+  generateVerifier,
+  randomBytes,
+  randomString,
+} from './pkce';
+export {
+  DEFAULT_DISCOVERY_TTL_MS,
+  DISCOVERY_PATH,
+  clearDiscoveryCache,
+  discover,
+  discoveryUrl,
+  normalizeIssuer,
+  seedDiscoveryCache,
+  type DiscoverOptions,
+} from './discovery';
+export { isStorageAdapter, memoryStorage, resolveStorage, webStorage } from './storage';
+export { AscenciaClient, createClient } from './client';
+
+// Le matching de permissions est celui du serveur, à la virgule près : un
+// `can()` côté client qui divergerait du verdict côté serveur serait pire
+// qu'inutile. Réexporté pour que les SDK n'aient pas à dépendre du RBAC.
+export { evaluate, matches } from '@ascencia/id-rbac';

package/src/pkce.ts

@@ -0,0 +1,84 @@
+/**
+ * PKCE (RFC 7636) sur WebCrypto seul.
+ *
+ * Uniquement `S256` : `plain` transmet le verifier en clair dans l'URL
+ * d'autorisation, ce qui annule exactement la protection qu'on cherche. L'IdP
+ * ne l'annonce pas et ne l'accepte pas non plus.
+ */
+
+import { AscenciaError } from './errors';
+
+export const CODE_CHALLENGE_METHOD = 'S256';
+
+/** 48 octets = 64 caractères base64url, bien au-dessus du minimum de 43 du RFC. */
+const DEFAULT_VERIFIER_BYTES = 48;
+
+const BASE64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
+function getCrypto(): Crypto {
+  const impl = globalThis.crypto;
+  if (!impl?.subtle) {
+    throw new AscenciaError(
+      'crypto_unavailable',
+      "WebCrypto est indisponible. En navigateur, il exige un contexte sécurisé (HTTPS ou localhost) ; sous Node, la version 20 ou plus.",
+    );
+  }
+  return impl;
+}
+
+/**
+ * Encodage base64url **sans padding**, écrit à la main : `btoa` n'existe pas
+ * partout et `Buffer` n'existe pas en navigateur. Trente lignes valent mieux
+ * qu'une dépendance ou qu'un polyfill conditionnel.
+ */
+export function base64UrlEncode(bytes: Uint8Array): string {
+  let out = '';
+
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i] ?? 0;
+    const b1 = bytes[i + 1];
+    const b2 = bytes[i + 2];
+
+    out += BASE64URL_ALPHABET.charAt(b0 >> 2);
+    out += BASE64URL_ALPHABET.charAt(((b0 & 0b11) << 4) | ((b1 ?? 0) >> 4));
+    if (b1 === undefined) break;
+
+    out += BASE64URL_ALPHABET.charAt(((b1 & 0b1111) << 2) | ((b2 ?? 0) >> 6));
+    if (b2 === undefined) break;
+
+    out += BASE64URL_ALPHABET.charAt(b2 & 0b111111);
+  }
+
+  return out;
+}
+
+export function randomBytes(length: number): Uint8Array {
+  return getCrypto().getRandomValues(new Uint8Array(length));
+}
+
+/** Chaîne aléatoire base64url, utilisable telle quelle dans une URL. */
+export function randomString(byteLength = 32): string {
+  return base64UrlEncode(randomBytes(byteLength));
+}
+
+/**
+ * Le verifier n'est composé que de caractères « unreserved » du RFC 7636, ce
+ * que garantit l'alphabet base64url.
+ */
+export function generateVerifier(byteLength = DEFAULT_VERIFIER_BYTES): string {
+  return base64UrlEncode(randomBytes(byteLength));
+}
+
+export async function challengeFromVerifier(verifier: string): Promise<string> {
+  const digest = await getCrypto().subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+  return base64UrlEncode(new Uint8Array(digest));
+}
+
+/** Le `state` doit porter au moins 16 octets d'entropie (docs/05-API.md §2). */
+export function generateState(): string {
+  return randomString(32);
+}
+
+export function generateNonce(): string {
+  return randomString(32);
+}

package/src/storage.ts

@@ -0,0 +1,103 @@
+/**
+ * Adaptateurs de stockage.
+ *
+ * Règle absolue : **rien ne lève ici**. Safari en navigation privée, Firefox
+ * avec `dom.storage.enabled=false` et un iframe tiers sans accès au stockage
+ * jettent une `SecurityError` dès le premier accès, parfois dès la simple
+ * lecture de `window.localStorage`. Une exception à cet endroit ferait tomber
+ * la page hôte alors que la seule conséquence raisonnable est de perdre la
+ * persistance : on retombe silencieusement en mémoire.
+ */
+
+import type { StorageAdapter, StoragePreference } from './types';
+
+export function memoryStorage(): StorageAdapter {
+  const map = new Map<string, string>();
+  return {
+    get: (key) => map.get(key) ?? null,
+    set: (key, value) => {
+      map.set(key, value);
+    },
+    remove: (key) => {
+      map.delete(key);
+    },
+  };
+}
+
+export function isStorageAdapter(value: unknown): value is StorageAdapter {
+  if (typeof value !== 'object' || value === null) return false;
+  const candidate = value as Partial<StorageAdapter>;
+  return (
+    typeof candidate.get === 'function' &&
+    typeof candidate.set === 'function' &&
+    typeof candidate.remove === 'function'
+  );
+}
+
+/**
+ * La lecture de la propriété elle-même peut lever, d'où le `try` autour de
+ * l'accès et pas seulement autour des appels.
+ */
+function pickWebStorage(kind: 'session' | 'local'): Storage | null {
+  try {
+    const store = kind === 'session' ? globalThis.sessionStorage : globalThis.localStorage;
+    if (!store) return null;
+
+    // Un stockage plein ou en lecture seule ne se révèle qu'à l'écriture :
+    // on paie une écriture sonde plutôt qu'un échec silencieux plus tard.
+    const probe = '__ascencia_probe__';
+    store.setItem(probe, '1');
+    store.removeItem(probe);
+    return store;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Stockage web avec repli mémoire. Le repli est aussi un miroir : si le quota
+ * saute en cours de route, les clés déjà écrites restent lisibles pour la
+ * durée de vie de la page, et une transaction PKCE en cours n'est pas perdue.
+ */
+export function webStorage(kind: 'session' | 'local'): StorageAdapter {
+  const store = pickWebStorage(kind);
+  const fallback = memoryStorage();
+  if (!store) return fallback;
+
+  return {
+    get: (key) => {
+      try {
+        return store.getItem(key) ?? fallback.get(key);
+      } catch {
+        return fallback.get(key);
+      }
+    },
+    set: (key, value) => {
+      fallback.set(key, value);
+      try {
+        store.setItem(key, value);
+      } catch {
+        // Quota dépassé ou permission retirée : le miroir mémoire suffit.
+      }
+    },
+    remove: (key) => {
+      fallback.remove(key);
+      try {
+        store.removeItem(key);
+      } catch {
+        // Rien à faire : la clé est de toute façon inaccessible.
+      }
+    },
+  };
+}
+
+export function resolveStorage(
+  preference: StoragePreference | undefined,
+  fallback: StoragePreference,
+): StorageAdapter {
+  const choice = preference ?? fallback;
+  if (isStorageAdapter(choice)) return choice;
+  if (choice === 'session') return webStorage('session');
+  if (choice === 'local') return webStorage('local');
+  return memoryStorage();
+}

package/src/types.ts

@@ -0,0 +1,253 @@
+/**
+ * Types publics du client OIDC d'Ascencia ID.
+ *
+ * Ce package est le socle commun des SDK React / Svelte et du widget : il ne
+ * connaît ni le DOM ni aucun framework, et n'a aucune dépendance runtime.
+ * Tout ce qui touche à la popup, aux composants ou aux stores vit un cran
+ * au-dessus.
+ *
+ * Voir docs/05-API.md et docs/06-INTEGRATION-SDK.md
+ */
+
+import type { AscenciaError } from './errors';
+
+/**
+ * Signature minimale de `fetch`. On ne référence pas `typeof fetch` pour que le
+ * package se type identiquement sous `lib: DOM` et sous les types de Node.
+ */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+/**
+ * Stockage clé/valeur synchrone.
+ *
+ * Aucune méthode ne doit lever : en navigation privée ou avec les cookies
+ * tiers bloqués, `localStorage` jette au premier accès et une exception ici
+ * casserait toute la page hôte. Voir `storage.ts`.
+ */
+export interface StorageAdapter {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+  remove(key: string): void;
+}
+
+/**
+ * `'memory'` est le défaut pour les jetons.
+ *
+ * `'local'` survit à la fermeture de l'onglet mais expose le jeton à tout XSS
+ * de la page : c'est un choix explicite du développeur, pas une valeur par
+ * défaut. Voir docs/08-SECURITY.md.
+ */
+export type StoragePreference = 'memory' | 'session' | 'local' | StorageAdapter;
+
+export interface AscenciaConfig {
+  /** Racine de l'IdP, sans slash final, ex. `https://id.ascencia.re`. */
+  issuer: string;
+  clientId: string;
+  redirectUri: string;
+  /** Défaut : `openid profile email ascencia.roles`. */
+  scopes?: readonly string[];
+  /**
+   * Slug de l'application, pour `/api/v1/me/context?app=…`.
+   * Sans lui, le contexte est résolu au niveau de la zone seulement.
+   */
+  app?: string;
+  /**
+   * Réservé aux clients confidentiels (Node, Bun, PHP). Ne **jamais** le
+   * placer dans un bundle navigateur : il y serait lisible par tout le monde.
+   */
+  clientSecret?: string;
+  /** Où vivent les jetons. Défaut : `'memory'`. */
+  storage?: StoragePreference;
+  /**
+   * Où vit la transaction PKCE (state, verifier, nonce). Défaut : `'session'`,
+   * parce qu'elle doit survivre à un aller-retour de navigation complet.
+   */
+  transactionStorage?: StoragePreference;
+  fetch?: FetchLike;
+  /**
+   * Marge avant l'expiration réelle du jeton d'accès, en secondes. Couvre la
+   * dérive d'horloge et le temps de vol de la requête. Défaut : 60.
+   */
+  clockSkewSeconds?: number;
+  /** Durée de vie du cache de découverte, en ms. Défaut : 1 h. */
+  discoveryTtlMs?: number;
+  /** Durée de vie du cache du contexte RBAC, en ms. Défaut : 60 s (docs/05-API.md §3). */
+  contextTtlMs?: number;
+  /**
+   * Métadonnées fournies à la main. Court-circuite l'appel réseau à
+   * `/.well-known/openid-configuration` : utile hors ligne et en test.
+   */
+  metadata?: DiscoveryDocument;
+  /** Préfixe des clés de stockage. Défaut : `'ascencia'`. */
+  storagePrefix?: string;
+}
+
+/**
+ * Document de découverte OIDC. Seuls les deux endpoints indispensables au flux
+ * `authorization_code` sont obligatoires ; le reste dépend du déploiement.
+ */
+export interface DiscoveryDocument {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  userinfo_endpoint?: string;
+  jwks_uri?: string;
+  end_session_endpoint?: string;
+  revocation_endpoint?: string;
+  introspection_endpoint?: string;
+  scopes_supported?: string[];
+  response_types_supported?: string[];
+  response_modes_supported?: string[];
+  grant_types_supported?: string[];
+  code_challenge_methods_supported?: string[];
+  id_token_signing_alg_values_supported?: string[];
+  token_endpoint_auth_methods_supported?: string[];
+  [claim: string]: unknown;
+}
+
+export interface Tokens {
+  accessToken: string;
+  tokenType: string;
+  /** Instant d'expiration en epoch ms, déjà résolu depuis `expires_in`. */
+  expiresAt: number;
+  refreshToken: string | null;
+  idToken: string | null;
+  scope: string[];
+}
+
+/**
+ * Identité normalisée.
+ *
+ * Les noms sont ceux de `/api/v1/me/context` (snake_case), pas ceux des claims
+ * OIDC : c'est cette forme que les attributs `data-ascencia-field` du widget et
+ * les SDK exposent au développeur. `getUser()` traduit `name` → `display_name`,
+ * `picture` → `avatar_url`, etc.
+ */
+export interface User {
+  id: string;
+  email: string | null;
+  email_verified: boolean;
+  display_name: string | null;
+  username: string | null;
+  avatar_url: string | null;
+  locale: string | null;
+}
+
+export interface ContextRole {
+  key: string;
+  name?: string;
+  color?: string | null;
+  priority: number;
+}
+
+export interface ContextMembership {
+  status: string;
+  nickname?: string | null;
+  profile?: Record<string, unknown>;
+  first_login_at?: string | null;
+}
+
+export interface ContextSession {
+  id: string;
+  /** Niveau d'assurance de l'authentification : 1 = mot de passe, 2 = MFA. */
+  aal?: number;
+  amr?: string[];
+  expires_at?: string;
+}
+
+/**
+ * Réponse de `GET /api/v1/me/context` : tout ce qu'il faut pour afficher une
+ * page en une seule requête.
+ */
+export interface AuthContext {
+  account: User;
+  realm: { slug: string; name?: string } | null;
+  application: { slug: string; name?: string } | null;
+  membership: ContextMembership | null;
+  roles: ContextRole[];
+  platform_roles: string[];
+  permissions: string[];
+  denied: string[];
+  session: ContextSession | null;
+  elevated: boolean;
+  etag?: string;
+}
+
+export type Prompt = 'none' | 'login' | 'consent' | 'select_account' | 'create';
+
+export interface SignInOptions {
+  /** `'register'` ouvre l'onglet inscription (traduit en `prompt=create`). */
+  screen?: 'login' | 'register';
+  /** Saute l'écran de choix et part directement chez le provider (extension Ascencia). */
+  provider?: string;
+  prompt?: Prompt;
+  /** Pré-remplit l'adresse e-mail. */
+  loginHint?: string;
+  /** Remplace les scopes de la configuration, le temps de cette autorisation. */
+  scopes?: readonly string[];
+  redirectUri?: string;
+  /** `'fr'`, `'en'`… */
+  uiLocales?: string;
+  /** `'aal2'` force la MFA pour cette autorisation. */
+  acrValues?: string;
+  /** Ré-authentification forcée si la session est plus vieille, en secondes. */
+  maxAge?: number;
+  /** `'web_message'` est le mode du widget popup (docs/04-AUTH-FLOWS.md §7). */
+  responseMode?: 'query' | 'fragment' | 'form_post' | 'web_message';
+  /** Paramètres bruts additionnels, ajoutés tels quels à l'URL. */
+  extraParams?: Record<string, string>;
+}
+
+/** Tout ce dont un appelant a besoin pour poursuivre le flux, popup ou redirection. */
+export interface AuthorizeRequest {
+  url: string;
+  state: string;
+  nonce: string;
+  codeVerifier: string;
+  codeChallenge: string;
+  redirectUri: string;
+}
+
+export interface CallbackParams {
+  code?: string | null;
+  state?: string | null;
+  error?: string | null;
+  error_description?: string | null;
+}
+
+/** Ce qu'accepte `handleCallback()` : l'URL de retour, ses paramètres, ou le message de la popup. */
+export type CallbackInput = string | URL | URLSearchParams | CallbackParams;
+
+export interface CallbackResult {
+  tokens: Tokens;
+  user: User;
+}
+
+export interface SignOutOptions {
+  /** Déconnexion SSO complète chez l'IdP, et pas seulement locale. */
+  global?: boolean;
+  postLogoutRedirectUri?: string;
+  /**
+   * Naviguer soi-même vers l'URL de déconnexion quand `global` est demandé.
+   * Défaut : `true` s'il y a un `location`. Mettre `false` pour récupérer
+   * l'URL et gérer la navigation à sa façon (framework router, popup…).
+   */
+  redirect?: boolean;
+}
+
+/** Les arguments passés à chaque événement, indexés par nom. */
+export interface AscenciaEventMap {
+  signin: [User];
+  signout: [];
+  refresh: [Tokens];
+  error: [AscenciaError];
+}
+
+export type AscenciaEventName = keyof AscenciaEventMap;
+
+export type AscenciaEventHandler<E extends AscenciaEventName> = (
+  ...args: AscenciaEventMap[E]
+) => void;
+
+/** Fonction de désabonnement renvoyée par `on()`. */
+export type Unsubscribe = () => void;