@liorian/oauth-kit 0.4.0-alpha.754ee48

package/README.md

@@ -0,0 +1,135 @@
+# @liorian/oauth-kit
+
+Client OAuth/SSO **côté serveur** pour les backends tiers (ex. `liorian-api-connect`,
+`liorian-api-store`, applications externes).
+
+Il permet de **vérifier et valider une session utilisateur** auprès de
+`liorian-api-core` — appareil + session + consentement — et de récupérer les
+informations de l'utilisateur (profil, e-mail, organisations, **rôles et
+permissions**) **uniquement dans la limite de l'accord donné par l'utilisateur
+lors de la connexion SSO** (scopes).
+
+Le backend tiers ne possède que sa **clé API applicative** (clé publique + secret).
+Il n'a jamais accès aux secrets, aux données critiques ni à la base de données de
+`liorian-api-core` : **toute la sécurité est exécutée par `liorian-api-core`**.
+
+## Pourquoi ce package ?
+
+- `liorian-api-core` concentre toutes les vérifications : signature HMAC de la clé
+  API, validité du jeton JWT, validation de l'appareil (`UserDevice`), validation de
+  la session persistée (`Session`), statut de l'utilisateur, et **consentement
+  utilisateur** (scopes).
+- Le backend tiers ne reçoit **aucune donnée non couverte par le consentement** :
+  pas de hash de mot de passe, pas de jetons, pas de clés, pas d'`auditId`, pas
+  d'informations internes.
+- Le backend tiers ne partage **aucun secret critique** (JWT_SECRET, clé de
+  chiffrement, secrets de session).
+
+## Workflow
+
+```
+Frontend (app tierce)          Backend tiers                liorian-api-core
+     │                              │                              │
+     │  1. login SSO (Autorisation Code + PKCE)                     │
+     │─────────────────────────────LIORIAN AUTH──────────────────▶│
+     │◀─────────────────── access_token (JWT) ──────────────────────│
+     │                                                              │
+     │  2. Bearer token envoyé au backend tiers                     │
+     │─────────────────────────────▶│                              │
+     │                              │  3. verifySession(token)      │
+     │                              │  + clé API + signature HMAC  │
+     │                              │──────────────────────────────▶│
+     │                              │     4. valide l'appareil (UserDevice) │
+     │                              │     5. valide la session (Session)    │
+     │                              │     6. vérifie le consentement        │
+     │                              │     7. renvoie utilisateur + rôles    │
+     │                              │        + permissions (scopes)         │
+     │                              │◀───────────────────────────────│
+```
+
+## Installation
+
+```bash
+bun add @liorian/oauth-kit   # (workspace monorepo : bun add @liorian/oauth-kit -w ... )
+```
+
+## Configuration
+
+```ts
+import {LiorianOAuthClient} from '@liorian/oauth-kit';
+
+const oauth = new LiorianOAuthClient({
+    baseUrl: 'https://api.liorian.local/api',  // ou LIORIAN_OAUTH_API_URL
+    apiKey: 'aaak-application-<hash>-sen',        // ou LIORIAN_OAUTH_API_KEY
+    apiSecret: '<secret applicatif>',             // ou LIORIAN_OAUTH_API_SECRET
+    clientId: 'mon-application',                  // ou LIORIAN_OAUTH_CLIENT_ID
+});
+```
+
+Variables d'environnement supportées :
+
+| Variable | Rôle |
+| --- | --- |
+| `LIORIAN_OAUTH_API_URL` | URL de base de `liorian-api-core` (défaut `https://localhost:5711/api`) |
+| `LIORIAN_OAUTH_API_KEY` | Clé API publique de l'application (`aaak-...-sen`) |
+| `LIORIAN_OAUTH_API_SECRET` | Secret de la clé API (signature HMAC) |
+| `LIORIAN_OAUTH_CLIENT_ID` | Identifiant OAuth de l'application |
+| `LIORIAN_OAUTH_AUTH_HOST` | Hôte de l'IdP Liorian Auth pour `buildAuthorizationUrl` |
+
+## Vérifier une session
+
+```ts
+import {OAuthVerificationError} from '@liorian/oauth-kit';
+
+async function handler(req) {
+    const token = req.headers.authorization?.replace(/^Bearer\s+/i, '');
+    try {
+        const result = await oauth.verifySession(token, {
+            userAgent: req.headers['user-agent'],
+        });
+        // result.user, result.roles, result.permissions, result.organizations…
+    } catch (e) {
+        if (e instanceof OAuthVerificationError) {
+            // 401 : session invalide / pas de consentement / clé API refusée
+            throw e;
+        }
+    }
+}
+```
+
+### Exemple de réponse
+
+```json
+{
+  "authenticated": true,
+  "scopes": ["openid", "profile", "email", "roles", "permissions"],
+  "user": {
+    "sub": "…",
+    "username": "…",
+    "name": {"firstname": "…", "lastname": "…"},
+    "email": "…"
+  },
+  "organizations": [{"id": "…", "name": "…", "isFounder": true, "role": "ROOT"}],
+  "roles": [{"id": "…", "name": "ROOT", "level": 99.99, "organizationId": "…"}],
+  "permissions": {"Customer": {"create": true, "read": true, "update": true, "delete": true}},
+  "device": {"id": "…", "userAgent": "…", "expiresAt": "…"},
+  "session": {"expiresAt": "…", "lastActiveAt": "…"}
+}
+```
+
+## Sécurité
+
+- **Authentification de l'application** : challenge horodaté + signature HMAC-SHA256
+  (anti-rejeu, comparaison à temps constant côté API). Le secret ne circule jamais.
+- **Validation de session complète** : JWT vérifié, `Session` persistée active et
+  non expirée, correspondance d'appareil (User-Agent), `UserDevice` non expiré,
+  utilisateur actif.
+- **Consentement utilisateur obligatoire** : seuls les scopes accordés lors du SSO
+  (et autorisés pour l'application) sont renvoyés. Aucune donnée sensible
+  (mots de passe, jetons, internalités) n'est exposée.
+- Le backend tiers ne reçoit **jamais** le `JWT_SECRET` ni les secrets de
+  `liorian-api-core`.
+
+## Licence
+
+MIT

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@liorian/oauth-kit",
+  "version": "0.4.0-alpha.754ee48",
+  "description": "Client OAuth/SSO côté serveur pour les backends tiers.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/bun": "^1.1.0",
+    "typescript": "^6.0.3"
+  }
+}

package/src/application/liorian-oauth.client.ts

@@ -0,0 +1,94 @@
+import {DEFAULT_SCOPES} from '../domain/oauth-scope.enum';
+import {OAuthClientError} from '../domain/oauth-exception';
+import {signatureService} from '../infrastructure/crypto/signature.service';
+import {HttpClient} from '../infrastructure/http/http-client';
+import type {AuthorizationUrlParams, LiorianOAuthOptions, VerifySessionOptions} from '../types/config.type';
+import type {OAuthVerifyRequest, OAuthVerificationResult} from '../types/verification.types';
+
+export const DEFAULT_OAUTH_API_URL = 'https://localhost:5711/api';
+export const DEFAULT_OAUTH_TIMEOUT_MS = 15000;
+
+/**
+ * Client SSO/OAuth de `@liorian/oauth-kit` à utiliser CÔTÉ SERVEUR par un backend
+ * tiers (liorian-api-connect, liorian-api-store, applications externes…).
+ *
+ * Le backend tiers possède uniquement sa clé API applicative (clé publique +
+ * secret) : il ne détient jamais les secrets ni les données sensibles de
+ * `liorian-api-core`. Toute la sécurité (validation de l'appareil, de la
+ * session, du consentement utilisateur) est exécutée par `liorian-api-core`.
+ */
+export class LiorianOAuthClient {
+    private readonly baseUrl: string;
+    private readonly apiKey: string;
+    private readonly apiSecret: string;
+    private readonly clientId: string;
+    private readonly timeoutMs: number;
+    private readonly http: HttpClient;
+
+    constructor(options: LiorianOAuthOptions) {
+        this.baseUrl = (options.baseUrl ?? process.env['LIORIAN_OAUTH_API_URL'] ?? DEFAULT_OAUTH_API_URL).replace(/\/$/, '');
+        this.apiKey = options.apiKey ?? process.env['LIORIAN_OAUTH_API_KEY'] ?? '';
+        this.apiSecret = options.apiSecret ?? process.env['LIORIAN_OAUTH_API_SECRET'] ?? '';
+        this.clientId = options.clientId ?? process.env['LIORIAN_OAUTH_CLIENT_ID'] ?? '';
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_OAUTH_TIMEOUT_MS;
+        this.http = new HttpClient(this.baseUrl, this.timeoutMs);
+
+        if (!this.apiKey || !this.apiSecret) {
+            throw new OAuthClientError(
+                '`@liorian/oauth-kit` requiert `apiKey` et `apiSecret` (ou les variables ' +
+                    'd’environnement LIORIAN_OAUTH_API_KEY / LIORIAN_OAUTH_API_SECRET).',
+            );
+        }
+    }
+
+    /**
+     * Vérifie et valide la session d'un utilisateur connecté via le SSO Liorian.
+     *
+     * Appelle `POST /oauth/verify` de liorian-api-core qui :
+     * 1. authentifie l'application tierce (clé API + signature HMAC du challenge) ;
+     * 2. valide l'appareil (UserDevice) et la session persistée (Session) ;
+     * 3. vérifie que l'utilisateur a consenti à partager ses données avec cette
+     *    application ;
+     * 4. ne renvoie que les données couvertes par le consentement (scopes).
+     *
+     * @param token Jeton de session de l'utilisateur (Bearer JWT émis au SSO).
+     */
+    async verifySession(token: string, opts: VerifySessionOptions = {}): Promise<OAuthVerificationResult> {
+        if (!token) {
+            throw new OAuthClientError('Le jeton de session à vérifier est requis.');
+        }
+
+        const challenge = signatureService.generateChallenge();
+        const signature = signatureService.sign(this.apiSecret, challenge);
+
+        const request: OAuthVerifyRequest = {
+            public_key: this.apiKey,
+            challenge,
+            signature,
+            token,
+            ...(opts.userAgent ? {user_agent: opts.userAgent} : {}),
+            ...(opts.ip ? {ip: opts.ip} : {}),
+        };
+
+        return this.http.post<OAuthVerificationResult>('/oauth/verify', request);
+    }
+
+    /**
+     * Construit l'URL d'autorisation SSO à destination du navigateur (frontend).
+     * L'application frontend redirige l'utilisateur vers l'IdP Liorian Auth.
+     */
+    buildAuthorizationUrl(params: AuthorizationUrlParams): string {
+        const base = process.env['LIORIAN_OAUTH_AUTH_HOST'] ?? process.env['LIORIAN_AUTH_HOST'] ?? 'https://localhost:5050';
+        const url = new URL('/auth/sign-in', base.replace(/\/$/, ''));
+        url.searchParams.set('response_type', params.responseType ?? 'code');
+        url.searchParams.set('client_id', params.clientId);
+        url.searchParams.set('redirect_uri', params.redirectUri);
+        url.searchParams.set('scope', params.scope ?? DEFAULT_SCOPES);
+        url.searchParams.set('state', params.state ?? '');
+        if (params.codeChallenge) {
+            url.searchParams.set('code_challenge', params.codeChallenge);
+            url.searchParams.set('code_challenge_method', params.codeChallengeMethod ?? 'S256');
+        }
+        return url.toString();
+    }
+}

package/src/domain/oauth-exception.ts

@@ -0,0 +1,27 @@
+/**
+ * Erreur technique du client `@liorian/oauth-kit` (réseau, timeout, réponse inattendue).
+ */
+export class OAuthClientError extends Error {
+    constructor(message: string, options?: {cause?: unknown}) {
+        super(message, options);
+        this.name = 'OAuthClientError';
+    }
+}
+
+/**
+ * Erreur métier renvoyée par liorian-api-core lors de la vérification
+ * d'une session (clé API invalide, session expirée, consentement révoqué…).
+ */
+export class OAuthVerificationError extends Error {
+    /** Statut HTTP renvoyé par l'API. */
+    readonly status: number;
+    /** Code d'erreur optionnel renvoyé par l'API. */
+    readonly code?: string;
+
+    constructor(message: string, status = 401, code?: string) {
+        super(message);
+        this.name = 'OAuthVerificationError';
+        this.status = status;
+        this.code = code;
+    }
+}

package/src/domain/oauth-scope.enum.ts

@@ -0,0 +1,28 @@
+/**
+ * Scopes OAuth (SSO Liorian) bien connus.
+ * Un backend tiers ne reçoit que les données couvertes par les scopes
+ * accordés par l'utilisateur lors de la connexion SSO (consentement).
+ */
+export enum OAuthScope {
+    /** Identifiant unique de session (OIDC `sub`). */
+    OPENID = 'openid',
+    /** Nom d'utilisateur, nom complet et avatar. */
+    PROFILE = 'profile',
+    /** Adresse e-mail principale. */
+    EMAIL = 'email',
+    /** Organisations auxquelles l'utilisateur appartient. */
+    ORGANIZATIONS = 'organizations',
+    /** Rôles de l'utilisateur (par organisation). */
+    ROLES = 'roles',
+    /** Permissions agrégées de l'utilisateur (par organisation). */
+    PERMISSIONS = 'permissions',
+}
+
+/** Scopes par défaut demandés lors d'une connexion SSO standard. */
+export const DEFAULT_SCOPES = `${OAuthScope.OPENID} ${OAuthScope.PROFILE} ${OAuthScope.EMAIL}`;
+
+/** Durée de validité maximale acceptée pour le challenge de signature (anti-rejeu). */
+export const CHALLENGE_TTL_MS = 2 * 60 * 1000;
+
+/** Séparateur utilisé entre l'horodatage et le nonce dans un challenge. */
+export const CHALLENGE_SEPARATOR = '.';

package/src/index.ts

@@ -0,0 +1,25 @@
+export {
+    LiorianOAuthClient,
+    DEFAULT_OAUTH_API_URL,
+    DEFAULT_OAUTH_TIMEOUT_MS,
+} from './application/liorian-oauth.client';
+export {OAuthScope, DEFAULT_SCOPES, CHALLENGE_TTL_MS, CHALLENGE_SEPARATOR} from './domain/oauth-scope.enum';
+export {OAuthClientError, OAuthVerificationError} from './domain/oauth-exception';
+export {SignatureService, signatureService} from './infrastructure/crypto/signature.service';
+export {HttpClient} from './infrastructure/http/http-client';
+export type {
+    LiorianOAuthOptions,
+    AuthorizationUrlParams,
+    VerifySessionOptions,
+} from './types/config.type';
+export type {SessionTokenPayload} from './types/session-token.type';
+export type {
+    OAuthVerifyRequest,
+    OAuthVerificationResult,
+    OAuthVerifiedUser,
+    OAuthVerifiedOrganization,
+    OAuthVerifiedRole,
+    OAuthPermissionCapability,
+    OAuthVerifiedDevice,
+    OAuthVerifiedSession,
+} from './types/verification.types';

package/src/infrastructure/crypto/signature.service.ts

@@ -0,0 +1,64 @@
+import {createHmac, randomBytes, timingSafeEqual} from 'node:crypto';
+import {CHALLENGE_SEPARATOR, CHALLENGE_TTL_MS} from '../../domain/oauth-scope.enum';
+
+/**
+ * Service de signature HMAC-SHA256 utilisé pour authentifier les appels du
+ * backend tiers auprès de liorian-api-core.
+ *
+ * Le challenge est un nonce horodaté (`<timestamp>. <nonce>`). Sa signature
+ * avec le secret applicatif prouve la possession de la clé API sans jamais
+ * transmettre le secret, et sa vérification temporelle limite le rejeu.
+ */
+export class SignatureService {
+    /**
+     * Génère un challenge frais : `<timestamp>.<nonce base64url>`.
+     */
+    generateChallenge(now: number = Date.now()): string {
+        const nonce = randomBytes(24).toString('base64url');
+        return `${now}${CHALLENGE_SEPARATOR}${nonce}`;
+    }
+
+    /**
+     * Signe le challenge avec le secret applicatif (HMAC-SHA256, base64).
+     * Algorithme identique à `CryptoService.hmacBase64` de `@liorian/api-resources`.
+     */
+    sign(secret: string, challenge: string): string {
+        return createHmac('sha256', secret).update(challenge).digest('base64');
+    }
+
+    /**
+     * Vérifie qu'un challenge est encore frais (anti-rejeu).
+     * Un challenge volé reste valable uniquement pendant `CHALLENGE_TTL_MS`.
+     */
+    isFresh(challenge: string, now: number = Date.now(), ttlMs: number = CHALLENGE_TTL_MS): boolean {
+        const separatorIndex = challenge.indexOf(CHALLENGE_SEPARATOR);
+        if (separatorIndex <= 0) {
+            return false;
+        }
+        const timestamp = Number(challenge.slice(0, separatorIndex));
+        if (!Number.isFinite(timestamp)) {
+            return false;
+        }
+        const delta = now - timestamp;
+        return delta >= 0 && delta <= ttlMs;
+    }
+
+    /**
+     * Compare deux signatures à temps constant (anti attaques par mesure du temps).
+     */
+    safeEqual(expected: string, actual: string): boolean {
+        if (expected.length !== actual.length) {
+            return false;
+        }
+        try {
+            return timingSafeEqual(
+                Buffer.from(expected, 'utf8'),
+                Buffer.from(actual, 'utf8'),
+            );
+        } catch {
+            return false;
+        }
+    }
+}
+
+export const signatureService = new SignatureService();

package/src/infrastructure/http/http-client.ts

@@ -0,0 +1,47 @@
+import {OAuthClientError, OAuthVerificationError} from '../../domain/oauth-exception';
+import type {RaitonErrorPayload} from '../../types/config.type';
+
+/**
+ * Client HTTP minimal (fetch natif) vers liorian-api-core.
+ * Gère le décodage de `RaitonResponses` (`{message, data, status}`) et lève
+ * des erreurs typées.
+ */
+export class HttpClient {
+    constructor(
+        private readonly baseUrl: string,
+        private readonly timeoutMs: number = 15000,
+    ) {}
+
+    async post<T>(path: string, body: unknown): Promise<T> {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+        try {
+            const response = await fetch(`${this.baseUrl}${path}`, {
+                method: 'POST',
+                headers: {'content-type': 'application/json'},
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+
+            const payload = await response.json().catch(() => null) as (RaitonErrorPayload & {status?: number}) | null;
+
+            if (!response.ok) {
+                const message = payload?.message || `Erreur HTTP ${response.status}`;
+                throw new OAuthVerificationError(message, response.status, payload?.code);
+            }
+
+            return (payload?.data ?? payload) as T;
+        } catch (error) {
+            if (error instanceof OAuthVerificationError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new OAuthClientError(`Délai d'attente dépassé pour ${path}`, {cause: error});
+            }
+            throw new OAuthClientError(`Appel réseau échoué pour ${path}`, {cause: error});
+        } finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/src/types/config.type.ts

@@ -0,0 +1,56 @@
+import {OAuthScope} from "../domain/oauth-scope.enum";
+
+/** Options de configuration du client `@liorian/oauth-kit`. */
+export interface LiorianOAuthOptions {
+    /**
+     * URL de base de liorian-api-core (suffixe `/api` inclus).
+     * Défaut : `https://localhost:5711/api`.
+     */
+    baseUrl?: string;
+    /**
+     * Clé API publique de l'application enregistrée dans liorian-api-core
+     * (format `aaak-${type}-${hash}-sen`).
+     */
+    apiKey?: string;
+    /**
+     * Secret associé à la clé API (jamais exposé côté client/frontend).
+     * Utilisé uniquement pour signer le challenge HMAC.
+     */
+    apiSecret?: string;
+    /**
+     * Identifiant OAuth de l'application (`clientId`). Sert à construire
+     * l'URL d'autorisation destinée au navigateur.
+     */
+    clientId?: string;
+    /** Timeout des appels HTTP (millisecondes). Défaut : 15000. */
+    timeoutMs?: number;
+}
+
+/** Paramètres de construction de l'URL d'autorisation SSO (frontend). */
+export interface AuthorizationUrlParams {
+    clientId: string;
+    redirectUri: string;
+    scope?: string;
+    state?: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: 'S256' | 'plain';
+    responseType?: 'code';
+}
+
+/** Forme du message d'erreur standardisé de RaitonResponses. */
+export interface RaitonErrorPayload {
+    message?: string;
+    code?: string;
+    data?: unknown;
+}
+
+export interface VerifySessionOptions {
+    /**
+     * User-Agent observé par le backend tiers au moment de la requête
+     * utilisateur. Permet à liorian-api-core de faire correspondre
+     * l'empreinte de l'appareil attendue avec la session.
+     */
+    userAgent?: string;
+    /** Adresse IP observée par le backend tiers (journalisable par l'API). */
+    ip?: string;
+}

package/src/types/session-token.type.ts

@@ -0,0 +1,13 @@
+/** Claims portés par le jeton de session JWT émis par liorian-api-core au sign-in SSO. */
+export interface SessionTokenPayload {
+    id: string;
+    username?: string;
+    email?: string;
+    device?: string;
+    userAgent?: string;
+    sub?: string;
+    iss?: string;
+    aud?: string;
+    iat?: number;
+    exp?: number;
+}

package/src/types/verification.types.ts

@@ -0,0 +1,93 @@
+import {OAuthScope} from "../domain/oauth-scope.enum";
+
+/** Corps de la requête envoyé à `POST /oauth/verify` de liorian-api-core. */
+export interface OAuthVerifyRequest {
+    /** Clé API publique de l'application tierce (format `aaak-...-sen`). */
+    public_key: string;
+    /** Challenge nonce horodaté (`<ts>.<nonce>`) signé en HMAC-SHA256. */
+    challenge: string;
+    /** Signature HMAC-SHA256 (base64) du challenge avec le secret applicatif. */
+    signature: string;
+    /** Jeton de session de l'utilisateur (Bearer JWT émis au SSO). */
+    token: string;
+    /** User-Agent observé par le backend tiers (validation de l'appareil). */
+    user_agent?: string;
+    /** Adresse IP observée par le backend tiers. */
+    ip?: string;
+}
+
+/** Identité minimale de l'utilisateur, filtrée par les scopes accordés. */
+export interface OAuthVerifiedUser {
+    /** Identifiant unique (OIDC `sub`), accordé par le scope `openid`. */
+    sub: string;
+    /** Alias technique, renvoyé uniquement si le scope `profile` est accordé. */
+    username?: string;
+    /** Nom complet (prénom + nom), accordé par le scope `profile`. */
+    name?: {
+        firstname?: string;
+        lastname?: string;
+        fullname?: string;
+    };
+    /** Adresse e-mail, renvoyée uniquement si le scope `email` est accordé. */
+    email?: string;
+    /** Avatar public, renvoyé uniquement si le scope `profile` est accordé. */
+    avatar?: {
+        id?: string;
+        filename?: string;
+        type?: string;
+        label?: string;
+        isPublic?: boolean;
+        createdAt?: string;
+    };
+}
+
+/** Organisation membre, renvoyée uniquement si le scope `organizations` est accordé. */
+export interface OAuthVerifiedOrganization {
+    id?: string;
+    name?: string;
+    isFounder?: boolean;
+    /** Nom du rôle dominant dans l'organisation si le scope `roles` est aussi accordé. */
+    role?: string;
+}
+
+/** Rôle de l'utilisateur dans une organisation (scope `roles`). */
+export interface OAuthVerifiedRole {
+    id?: string;
+    name: string;
+    level?: number;
+    organizationId?: string;
+}
+
+/** Capacité CRUD d'un domaine (scope `permissions`). */
+export interface OAuthPermissionCapability {
+    create: boolean;
+    read: boolean;
+    update: boolean;
+    delete: boolean;
+}
+
+/** Informations sur l'appareil validé (jamais le jeton associé). */
+export interface OAuthVerifiedDevice {
+    id?: string;
+    userAgent?: string;
+    expiresAt?: string;
+}
+
+/** Informations sur la session validée (jamais le jeton associé). */
+export interface OAuthVerifiedSession {
+    expiresAt?: string;
+    lastActiveAt?: string;
+}
+
+/** Résultat de la vérification d'une session par liorian-api-core. */
+export interface OAuthVerificationResult {
+    authenticated: true;
+    /** Scopes effectivement accordés par le consentement (intersection client × consentement). */
+    scopes: OAuthScope[];
+    user: OAuthVerifiedUser;
+    organizations: OAuthVerifiedOrganization[];
+    roles: OAuthVerifiedRole[];
+    permissions: Record<string, OAuthPermissionCapability>;
+    device?: OAuthVerifiedDevice;
+    session?: OAuthVerifiedSession;
+}