@kourouma/express-authkit 0.0.0-stage → 0.1.0-rc.1

package/src/providers/jwt-token-provider.js

@@ -0,0 +1,112 @@
+import { SignJWT, errors as joseErrors, jwtVerify } from "jose";
+
+import { resolveJwtOptions } from "../config/jwt-options.js";
+import { InvalidInputError, InvalidTokenError, TokenExpiredError } from "../core/errors.js";
+import { MAX_TOKEN_LENGTH } from "../core/input-limits.js";
+import { subjectInvalid } from "../core/messages.js";
+
+/**
+ * Type de média RFC 9068 pour les jetons d’accès JWT. L’exiger lors de la
+ * vérification empêche d’autres JWT signés avec la même clé (jetons d’identité,
+ * liens de confirmation d’e-mail…) d’être acceptés comme jetons d’accès.
+ */
+const ACCESS_TOKEN_TYPE = "at+jwt";
+const REQUIRED_CLAIMS = Object.freeze(["sub", "iss", "aud", "exp", "iat", "jti"]);
+const MAX_SUBJECT_LENGTH = 256;
+
+/**
+ * Crée un {@link import("../core/contracts/token-provider.js").TokenProvider}
+ * qui émet et vérifie des jetons d’accès JWT signés en HMAC avec `jose`.
+ *
+ * Les jetons ne contiennent que des revendications standard (`sub`, `iss`,
+ * `aud`, `iat`, `exp`, `jti`) : aucune donnée personnelle ou sensible n’est
+ * placée dans la charge utile, qui est encodée mais non chiffrée.
+ *
+ * @param {import("../config/jwt-options.js").JwtOptions} options
+ * @returns {import("../core/contracts/token-provider.js").TokenProvider}
+ * @throws {import("../core/errors.js").ConfigurationError}
+ */
+export function createJwtTokenProvider(options) {
+  const config = resolveJwtOptions(options);
+
+  const verifyOptions = Object.freeze({
+    algorithms: [config.algorithm],
+    issuer: config.issuer,
+    audience: config.audience,
+    typ: ACCESS_TOKEN_TYPE,
+    clockTolerance: config.clockToleranceSeconds,
+    // Also makes jose reject tokens whose `iat` lies in the future, and tokens
+    // older than the configured lifetime (e.g. after shortening it).
+    maxTokenAge: config.expiresInSeconds,
+    requiredClaims: [...REQUIRED_CLAIMS]
+  });
+
+  /**
+   * @param {{ subject: string }} input
+   * @returns {Promise<import("../core/contracts/token-provider.js").IssuedToken>}
+   */
+  async function issue(input) {
+    const subject = input?.subject;
+    if (typeof subject !== "string" || subject.length === 0 || subject.length > MAX_SUBJECT_LENGTH) {
+      throw new InvalidInputError(subjectInvalid(MAX_SUBJECT_LENGTH));
+    }
+
+    const issuedAt = Math.floor(Date.now() / 1000);
+    const expiresAt = issuedAt + config.expiresInSeconds;
+    const tokenId = globalThis.crypto.randomUUID();
+
+    const token = await new SignJWT({})
+      .setProtectedHeader({ alg: config.algorithm, typ: ACCESS_TOKEN_TYPE })
+      .setSubject(subject)
+      .setIssuer(config.issuer)
+      .setAudience(config.audience)
+      .setIssuedAt(issuedAt)
+      .setExpirationTime(expiresAt)
+      .setJti(tokenId)
+      .sign(config.key);
+
+    return { token, tokenId, issuedAt, expiresAt };
+  }
+
+  /**
+   * @param {string} token
+   * @returns {Promise<import("../core/contracts/token-provider.js").VerifiedTokenClaims>}
+   */
+  async function verify(token) {
+    if (typeof token !== "string" || token.length === 0 || token.length > MAX_TOKEN_LENGTH) {
+      throw new InvalidTokenError();
+    }
+
+    let payload;
+    try {
+      ({ payload } = await jwtVerify(token, config.key, verifyOptions));
+    } catch (error) {
+      throw toTokenError(error);
+    }
+
+    const { sub, jti, iat, exp } = payload;
+    if (typeof sub !== "string" || sub.length === 0 || sub.length > MAX_SUBJECT_LENGTH || typeof jti !== "string") {
+      throw new InvalidTokenError();
+    }
+    return { subject: sub, tokenId: jti, issuedAt: /** @type {number} */ (iat), expiresAt: /** @type {number} */ (exp) };
+  }
+
+  return Object.freeze({ issue, verify });
+}
+
+/**
+ * Convertit les erreurs de `jose` en erreurs de la bibliothèque. Toute erreur
+ * qui ne vient pas de JOSE est inattendue et est propagée sans modification.
+ *
+ * @param {unknown} error
+ * @returns {unknown}
+ */
+function toTokenError(error) {
+  if (error instanceof joseErrors.JWTExpired) {
+    return new TokenExpiredError({ cause: error });
+  }
+  if (error instanceof joseErrors.JOSEError) {
+    return new InvalidTokenError({ cause: error });
+  }
+  return error;
+}

package/types/adapters/express/bearer-token.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Extrait le jeton d’accès d’un en-tête `Authorization`.
+ *
+ * Un en-tête utilisant un autre schéma (par exemple `Basic`) est traité comme
+ * une absence de jeton ; une valeur `Bearer` mal formée est invalide.
+ *
+ * @param {string | undefined} headerValue
+ * @returns {string}
+ * @throws {TokenMissingError | InvalidTokenError}
+ */
+export declare function extractBearerToken(headerValue: string | undefined): string;

package/types/adapters/express/http-errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @param {unknown} error
+ * @returns {number | undefined} Statut à envoyer, ou `undefined` si ce n’est pas une erreur client.
+ */
+export declare function getClientErrorStatus(error: unknown): number | undefined;
+/**
+ * Comme {@link getClientErrorStatus}, mais reconnaît aussi les erreurs du
+ * parseur JSON d’Express (`express.json()`) : un JSON mal formé ou trop
+ * volumineux reçoit une réponse JSON propre au lieu de la page d’erreur HTML
+ * d’Express, qui peut afficher la pile d’appels en développement.
+ *
+ * @param {unknown} error
+ * @returns {{ error: import("../../core/errors.js").AuthKitError, status: number } | undefined}
+ */
+export declare function resolveClientError(error: unknown): {
+    error: import("../../core/errors.js").AuthKitError;
+    status: number;
+} | undefined;
+/**
+ * Envoie une erreur d’authentification client au format JSON.
+ *
+ * Seuls le `code` stable et le `message` public sont envoyés : jamais la pile,
+ * la cause ou la raison interne de l’échec.
+ *
+ * @param {import("express").Response} res
+ * @param {import("../../core/errors.js").AuthKitError} error
+ * @param {number} status
+ * @param {string} realm
+ */
+export declare function sendClientError(res: import("express").Response, error: import("../../core/errors.js").AuthKitError, status: number, realm: string): void;

package/types/adapters/express/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Express AuthKit — adaptateur Express.js (`@kourouma/express-authkit/express`).
+ *
+ * Ce module n’importe pas Express : il produit uniquement des middlewares
+ * standard `(req, res, next)`, compatibles avec Express 4 et 5.
+ *
+ * @module @kourouma/express-authkit/express
+ */
+export type ExpressAuthOptions = {
+    /**
+     * Domaine annoncé dans l’en-tête `WWW-Authenticate`.
+     */
+    realm?: string;
+};
+export type ExpressAuthorizationRequirement = string | {
+    anyRole?: string[];
+    allPermissions?: string[];
+    check?: (user: import("../../core/contracts/auth-principal.js").AuthPrincipal, req: import("express").Request) => boolean | Promise<boolean>;
+};
+export type LoginHandlerOptions = {
+    /**
+     * Champ du corps JSON contenant l’identifiant (par exemple `"email"`).
+     */
+    identifierField?: string;
+};
+export type ExpressAuth = Readonly<{
+    authenticate: () => import("express").RequestHandler;
+    authorize: (requirement: ExpressAuthorizationRequirement) => import("express").RequestHandler;
+    login: (options?: LoginHandlerOptions) => import("express").RequestHandler;
+    refresh: () => import("express").RequestHandler;
+    logout: () => import("express").RequestHandler;
+    errorHandler: () => import("express").ErrorRequestHandler;
+}>;
+/**
+ * Crée l’intégration Express pour un moteur construit avec `createAuthKit()`.
+ *
+ * @example
+ * const expressAuth = createExpressAuth(auth);
+ * app.post("/login", express.json(), expressAuth.login());
+ * app.get("/profile", expressAuth.authenticate(), (req, res) => {
+ *   res.json({ userId: req.auth.userId });
+ * });
+ *
+ * @param {import("../../factory/create-auth-kit.js").AuthKit} auth
+ * @param {ExpressAuthOptions} [options]
+ * @returns {ExpressAuth}
+ */
+export declare function createExpressAuth(auth: import("../../factory/create-auth-kit.js").AuthKit, options?: ExpressAuthOptions): ExpressAuth;
+
+declare global {
+  namespace Express {
+    interface Request {
+      /** Utilisateur authentifié. Présent après `expressAuth.authenticate()`. */
+      auth?: import("../../core/contracts/auth-principal.js").AuthPrincipal;
+    }
+  }
+}

package/types/config/assertions.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Petites fonctions de vérification partagées par les validateurs de configuration.
+ *
+ * @module config/assertions
+ */
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * @param {unknown} value
+ * @param {string} name
+ * @returns {asserts value is Record<string, unknown>}
+ */
+export declare function assertPlainObject(value: unknown, name: string): asserts value is Record<string, unknown>;
+/**
+ * Refuse les clés inconnues afin qu’une faute de frappe (par exemple
+ * `expiresIn` au lieu de `expiresInSeconds`) ne passe pas inaperçue.
+ *
+ * @param {Record<string, unknown>} object
+ * @param {readonly string[]} allowedKeys
+ * @param {string} name
+ */
+export declare function assertKnownKeys(object: Record<string, unknown>, allowedKeys: readonly string[], name: string): void;
+/**
+ * @param {unknown} value
+ * @param {string} name
+ * @param {number} maxLength
+ * @returns {asserts value is string}
+ */
+export declare function assertNonEmptyString(value: unknown, name: string, maxLength: number): asserts value is string;
+/**
+ * @param {unknown} value
+ * @param {string} name
+ * @param {number} min
+ * @param {number} max
+ * @returns {asserts value is number}
+ */
+export declare function assertIntegerInRange(value: unknown, name: string, min: number, max: number): asserts value is number;

package/types/config/auth-kit-options.d.ts

@@ -0,0 +1,41 @@
+export type ProviderOverrides = {
+    /**
+     * Remplace le fournisseur Argon2id. Les options `password` doivent alors être absentes.
+     */
+    password?: import("../core/contracts/password-provider.js").PasswordProvider;
+    /**
+     * Remplace le fournisseur JWT. Les options `jwt` doivent alors être absentes.
+     */
+    token?: import("../core/contracts/token-provider.js").TokenProvider;
+};
+export type AuthKitOptions = {
+    /**
+     * Dépôt d’utilisateurs de l’application.
+     */
+    users: import("../core/contracts/user-repository.js").UserRepository;
+    /**
+     * Obligatoire sans `providers.token`.
+     */
+    jwt?: import("./jwt-options.js").JwtOptions;
+    /**
+     * Paramètres de coût Argon2id.
+     */
+    password?: import("./password-options.js").PasswordOptions;
+    /**
+     * Active les jetons de rafraîchissement (désactivés par défaut).
+     */
+    refreshTokens?: import("./refresh-token-options.js").RefreshTokenOptions;
+    /**
+     * Implémentations personnalisées des fournisseurs.
+     */
+    providers?: ProviderOverrides;
+};
+/**
+ * Valide la structure principale des options. Les valeurs imbriquées sont
+ * validées par leurs résolveurs et leurs vérifications de contrat dédiés.
+ *
+ * @param {unknown} options
+ * @returns {AuthKitOptions}
+ * @throws {ConfigurationError}
+ */
+export declare function validateAuthKitOptions(options: unknown): AuthKitOptions;

package/types/config/defaults.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Valeurs sûres par défaut et limites acceptées.
+ *
+ * @module config/defaults
+ */
+/**
+ * Algorithmes JWT acceptés pour une signature par secret partagé, avec la taille
+ * minimale de clé exigée par la RFC 7518 §3.2.
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+export declare const JWT_ALGORITHM_MIN_KEY_BYTES: Readonly<Record<string, number>>;
+export declare const JWT_DEFAULTS: Readonly<{
+    algorithm: "HS256";
+    /** 15 minutes : une courte durée réduit l’impact d’un jeton divulgué. */
+    expiresInSeconds: 900;
+    clockToleranceSeconds: 0;
+}>;
+export declare const JWT_LIMITS: Readonly<{
+    minExpiresInSeconds: 30;
+    /** Les jetons d’accès ne sont pas révocables : une durée de plus d’un jour est refusée. */
+    maxExpiresInSeconds: 86400;
+    maxClockToleranceSeconds: 60;
+    maxClaimLength: 256;
+}>;
+/**
+ * Valeurs Argon2id par défaut : « deuxième option recommandée » de la RFC 9106
+ * (64 Mio, t=3, p=4), plus forte que le minimum OWASP.
+ */
+export declare const ARGON2_DEFAULTS: Readonly<{
+    memoryCost: 65536;
+    timeCost: 3;
+    parallelism: 4;
+}>;
+/**
+ * Seuils en dessous desquels Argon2id est refusé : au moins 19 Mio de mémoire
+ * et 2 itérations, selon OWASP.
+ */
+export declare const ARGON2_LIMITS: Readonly<{
+    minMemoryCost: 19456;
+    maxMemoryCost: 4194304;
+    minTimeCost: 2;
+    maxTimeCost: 20;
+    minParallelism: 1;
+    maxParallelism: 16;
+}>;
+export declare const REFRESH_TOKEN_DEFAULTS: Readonly<{
+    /** 14 jours : l’utilisateur reste connecté s’il revient au moins toutes les deux semaines. */
+    expiresInSeconds: 1209600;
+}>;
+export declare const REFRESH_TOKEN_LIMITS: Readonly<{
+    minExpiresInSeconds: 300;
+    /** 90 jours au plus : au-delà, une session oubliée reste exploitable trop longtemps. */
+    maxExpiresInSeconds: 7776000;
+}>;

package/types/config/jwt-options.d.ts

@@ -0,0 +1,42 @@
+export type JwtOptions = {
+    /**
+     * Clé de signature partagée produite par un générateur sûr (≥ 32 octets pour HS256). Une valeur absente (par exemple une variable d’environnement non définie) est acceptée par les types mais arrête createAuthKit() avec un message clair.
+     */
+    secret: string | Uint8Array | undefined;
+    /**
+     * Valeur de la revendication `iss`, contrôlée à la vérification.
+     */
+    issuer: string;
+    /**
+     * Valeur de la revendication `aud`, contrôlée à la vérification.
+     */
+    audience: string;
+    /**
+     * Durée de vie du jeton (30 à 86 400 secondes).
+     */
+    expiresInSeconds?: number;
+    /**
+     * Seul algorithme accepté à la vérification.
+     */
+    algorithm?: "HS256" | "HS384" | "HS512";
+    /**
+     * Décalage d’horloge accepté entre instances (0 à 60 secondes).
+     */
+    clockToleranceSeconds?: number;
+};
+export type ResolvedJwtOptions = Readonly<{
+    key: Uint8Array;
+    issuer: string;
+    audience: string;
+    expiresInSeconds: number;
+    algorithm: string;
+    clockToleranceSeconds: number;
+}>;
+/**
+ * Valide les options JWT, applique des valeurs sûres et refuse les valeurs dangereuses.
+ *
+ * @param {unknown} options
+ * @returns {ResolvedJwtOptions}
+ * @throws {ConfigurationError}
+ */
+export declare function resolveJwtOptions(options: unknown): ResolvedJwtOptions;

package/types/config/password-options.d.ts

@@ -0,0 +1,23 @@
+export type PasswordOptions = {
+    /**
+     * Mémoire en Kio (minimum 19 456, soit 19 Mio).
+     */
+    memoryCost?: number;
+    /**
+     * Nombre d’itérations (minimum 2).
+     */
+    timeCost?: number;
+    /**
+     * Niveau de parallélisme (1 à 16).
+     */
+    parallelism?: number;
+};
+export type ResolvedPasswordOptions = Readonly<Required<PasswordOptions>>;
+/**
+ * Valide les options Argon2id et refuse les paramètres sous le seuil OWASP.
+ *
+ * @param {unknown} [options]
+ * @returns {ResolvedPasswordOptions}
+ * @throws {import("../core/errors.js").ConfigurationError}
+ */
+export declare function resolvePasswordOptions(options?: unknown): ResolvedPasswordOptions;

package/types/config/refresh-token-options.d.ts

@@ -0,0 +1,21 @@
+export type RefreshTokenOptions = {
+    /**
+     *   Stockage des jetons (votre base de données, ou `createInMemoryRefreshTokenStore()` en développement).
+     */
+    store: import("../core/contracts/refresh-token-store.js").RefreshTokenStore;
+    /**
+     * Durée de vie d’un jeton de rafraîchissement
+     * (14 jours par défaut, de 5 minutes à 90 jours). Chaque rotation repart de zéro.
+     */
+    expiresInSeconds?: number;
+};
+export type ResolvedRefreshTokenOptions = Readonly<{
+    store: import("../core/contracts/refresh-token-store.js").RefreshTokenStore;
+    expiresInSeconds: number;
+}>;
+/**
+ * @param {unknown} options
+ * @returns {ResolvedRefreshTokenOptions}
+ * @throws {ConfigurationError | import("../core/errors.js").ContractViolationError}
+ */
+export declare function resolveRefreshTokenOptions(options: unknown): ResolvedRefreshTokenOptions;

package/types/config/secret-strength.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @param {unknown} secret
+ * @param {number} minBytes
+ * @returns {Uint8Array} Secret encodé en octets, prêt pour le fournisseur JWT.
+ * @throws {ConfigurationError}
+ */
+export declare function assertStrongSecret(secret: unknown, minBytes: number): Uint8Array;

package/types/core/authentication-service.d.ts

@@ -0,0 +1,37 @@
+export type UserRepository = import("./contracts/user-repository.js").UserRepository;
+export type PasswordProvider = import("./contracts/password-provider.js").PasswordProvider;
+export type TokenProvider = import("./contracts/token-provider.js").TokenProvider;
+export type AuthenticationService = import("./contracts/authentication-service.js").AuthenticationService;
+export type LoginCredentials = import("./contracts/authentication-service.js").LoginCredentials;
+export type LoginResult = import("./contracts/authentication-service.js").LoginResult;
+export type AuthPrincipal = import("./contracts/auth-principal.js").AuthPrincipal;
+/**
+ * @typedef {import("./contracts/user-repository.js").UserRepository} UserRepository
+ * @typedef {import("./contracts/password-provider.js").PasswordProvider} PasswordProvider
+ * @typedef {import("./contracts/token-provider.js").TokenProvider} TokenProvider
+ * @typedef {import("./contracts/authentication-service.js").AuthenticationService} AuthenticationService
+ * @typedef {import("./contracts/authentication-service.js").LoginCredentials} LoginCredentials
+ * @typedef {import("./contracts/authentication-service.js").LoginResult} LoginResult
+ * @typedef {import("./contracts/auth-principal.js").AuthPrincipal} AuthPrincipal
+ */
+/**
+ * Crée le service d’authentification indépendant du framework.
+ *
+ * La fabrique doit avoir validé les dépendances au préalable. Ce service ne
+ * conserve aucun état utilisateur : il peut être partagé entre les requêtes
+ * et entre plusieurs processus derrière un répartiteur de charge.
+ *
+ * @param {object} dependencies
+ * @param {UserRepository} dependencies.users
+ * @param {PasswordProvider} dependencies.passwordProvider
+ * @param {TokenProvider} dependencies.tokenProvider
+ * @param {ReturnType<typeof import("./refresh-token-service.js").createRefreshTokenService>} [dependencies.refreshTokens]
+ *   Service des jetons de rafraîchissement ; absent si la fonctionnalité n’est pas activée.
+ * @returns {AuthenticationService}
+ */
+export declare function createAuthenticationService({ users, passwordProvider, tokenProvider, refreshTokens }: {
+    users: UserRepository;
+    passwordProvider: PasswordProvider;
+    tokenProvider: TokenProvider;
+    refreshTokens?: ReturnType<typeof import("./refresh-token-service.js").createRefreshTokenService>;
+}): AuthenticationService;

package/types/core/authorization.d.ts

@@ -0,0 +1,40 @@
+export type AuthorizationRequirement = string | {
+    anyRole?: string[];
+    allPermissions?: string[];
+    check?: (principal: import("./contracts/auth-principal.js").AuthPrincipal, context?: unknown) => boolean | Promise<boolean>;
+};
+export type NormalizedAuthorizationRequirement = Readonly<{
+    anyRole: readonly string[];
+    allPermissions: readonly string[];
+    check: ((principal: import("./contracts/auth-principal.js").AuthPrincipal, context?: unknown) => boolean | Promise<boolean>) | undefined;
+}>;
+/**
+ * Valide une règle d’accès au démarrage, pour qu’une faute (rôle vide, clé
+ * mal orthographiée…) soit signalée avant la première requête.
+ *
+ * @param {unknown} requirement
+ * @returns {NormalizedAuthorizationRequirement}
+ * @throws {ConfigurationError}
+ */
+export declare function normalizeAuthorizationRequirement(requirement: unknown): NormalizedAuthorizationRequirement;
+/**
+ * Indique si un utilisateur authentifié respecte une règle d’accès.
+ *
+ * - `anyRole` : l’utilisateur doit avoir **au moins un** de ces rôles ;
+ * - `allPermissions` : il doit avoir **toutes** ces permissions ;
+ * - `check` : fonction personnalisée, appelée en dernier, avec `context`
+ *   (la requête HTTP avec l’adaptateur Express).
+ *
+ * @example
+ * await isAuthorized(principal, "admin");
+ * await isAuthorized(principal, { allPermissions: ["orders:write"] });
+ * await isAuthorized(principal, { check: (user, req) => user.userId === req.params.id }, req);
+ *
+ * @param {import("./contracts/auth-principal.js").AuthPrincipal} principal
+ * @param {AuthorizationRequirement | NormalizedAuthorizationRequirement} requirement
+ * @param {unknown} [context] Information transmise à `check` (par exemple la requête).
+ * @returns {Promise<boolean>}
+ * @throws {ConfigurationError} Si la règle est invalide.
+ * @throws {ContractViolationError} Si `check` ne renvoie pas un booléen.
+ */
+export declare function isAuthorized(principal: import("./contracts/auth-principal.js").AuthPrincipal, requirement: AuthorizationRequirement | NormalizedAuthorizationRequirement, context?: unknown): Promise<boolean>;

package/types/core/contracts/assert-contract.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Vérifie que `candidate` expose toutes les méthodes de `methodNames`.
+ *
+ * JavaScript n’a pas d’interfaces : les contrats sont vérifiés par leur forme
+ * au démarrage afin de signaler clairement une dépendance mal configurée.
+ *
+ * @param {unknown} candidate Dépendance injectée.
+ * @param {string} contractName Nom utilisé dans les messages d’erreur.
+ * @param {readonly string[]} methodNames Méthodes exigées par le contrat.
+ * @returns {void}
+ * @throws {ContractViolationError}
+ */
+export declare function assertImplements(candidate: unknown, contractName: string, methodNames: readonly string[]): void;

package/types/core/contracts/auth-principal.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Identité validée d’un utilisateur authentifié.
+ *
+ * Le principal ne contient que des données non sensibles issues d’un jeton
+ * vérifié. Il ne contient jamais le hash du mot de passe ni le jeton brut.
+ * Il est figé pour empêcher les middlewares suivants de le modifier.
+ *
+ * Les rôles et permissions viennent du repository, relu à chaque requête :
+ * ils ne sont jamais écrits dans le jeton, et un changement de rôle
+ * s’applique immédiatement.
+ *
+ * @typedef {Readonly<{
+ *   userId: string,
+ *   tokenId: string,
+ *   issuedAt: number,
+ *   expiresAt: number,
+ *   roles: readonly string[],
+ *   permissions: readonly string[]
+ * }>} AuthPrincipal
+ */
+export type AuthPrincipal = Readonly<{
+    userId: string;
+    tokenId: string;
+    issuedAt: number;
+    expiresAt: number;
+    roles: readonly string[];
+    permissions: readonly string[];
+}>;
+/**
+ * @param {import("./token-provider.js").VerifiedTokenClaims | import("./token-provider.js").IssuedToken} claims
+ * @param {{ id: string, roles: readonly string[], permissions: readonly string[] }} user
+ * @returns {AuthPrincipal}
+ */
+export declare function createAuthPrincipal(claims: import("./token-provider.js").VerifiedTokenClaims | import("./token-provider.js").IssuedToken, user: {
+    id: string;
+    roles: readonly string[];
+    permissions: readonly string[];
+}): AuthPrincipal;