First Implementation of Core Project (#2)

* First Implementation of Core Project

* Extensions & Options & Validators

* Errors & Utilities & Multi Tenancy Support & Events

* Fixes

* Add XML Definitions

Author: mckaragoz

src/CodeBeam.UltimateAuth.Core/Abstractions/.gitkeep

@@ -0,0 +1,21 @@
+namespace CodeBeam.UltimateAuth.Core.Abstractions
+{
+    /// <summary>
+    /// Represents the minimal user abstraction required by UltimateAuth.
+    /// Includes the unique user identifier and an optional set of claims that
+    /// may be used during authentication or session creation.
+    /// </summary>
+    public interface IUser<TUserId>
+    {
+        /// <summary>
+        /// Gets the unique identifier of the user.
+        /// </summary>
+        TUserId UserId { get; }
+
+        /// <summary>
+        /// Gets an optional collection of user claims that may be used to construct
+        /// session-level claim snapshots. Implementations may return <c>null</c> if no claims are available.
+        /// </summary>
+        IReadOnlyDictionary<string, object>? Claims { get; }
+    }
+}

src/CodeBeam.UltimateAuth.Core/Abstractions/IUser.cs

@@ -0,0 +1,45 @@
+namespace CodeBeam.UltimateAuth.Core.Abstractions
+{
+    /// <summary>
+    /// Defines conversion logic for transforming user identifiers between
+    /// strongly typed values, string representations, and binary formats.
+    /// Implementations enable consistent storage, token serialization,
+    /// and multitenant key partitioning.
+    /// </summary>
+    public interface IUserIdConverter<TUserId>
+    {
+        /// <summary>
+        /// Converts the typed user identifier into its canonical string representation.
+        /// </summary>
+        /// <param name="id">The user identifier to convert.</param>
+        /// <returns>A stable and reversible string representation of the identifier.</returns>
+        string ToString(TUserId id);
+
+        /// <summary>
+        /// Converts the typed user identifier into a binary representation suitable for efficient storage or hashing operations.
+        /// </summary>
+        /// <param name="id">The user identifier to convert.</param>
+        /// <returns>A byte array representing the identifier.</returns>
+        byte[] ToBytes(TUserId id);
+
+        /// <summary>
+        /// Reconstructs a typed user identifier from its string representation.
+        /// </summary>
+        /// <param name="value">The string-encoded identifier.</param>
+        /// <returns>The reconstructed user identifier.</returns>
+        /// <exception cref="FormatException">
+        /// Thrown when the input value cannot be parsed into a valid identifier.
+        /// </exception>
+        TUserId FromString(string value);
+
+        /// <summary>
+        /// Reconstructs a typed user identifier from its binary representation.
+        /// </summary>
+        /// <param name="binary">The byte array containing the encoded identifier.</param>
+        /// <returns>The reconstructed user identifier.</returns>
+        /// <exception cref="FormatException">
+        /// Thrown when the input binary value cannot be parsed into a valid identifier.
+        /// </exception>
+        TUserId FromBytes(byte[] binary);
+    }
+}

src/CodeBeam.UltimateAuth.Core/Abstractions/IUserIdConverter.cs

@@ -0,0 +1,23 @@
+namespace CodeBeam.UltimateAuth.Core.Abstractions
+{
+    /// <summary>
+    /// Resolves the appropriate <see cref="IUserIdConverter{TUserId}"/> instance
+    /// for a given user identifier type. Used internally by UltimateAuth to
+    /// ensure consistent serialization and parsing of user IDs across all components.
+    /// </summary>
+    public interface IUserIdConverterResolver
+    {
+        /// <summary>
+        /// Retrieves the registered <see cref="IUserIdConverter{TUserId}"/> for the specified user ID type.
+        /// </summary>
+        /// <typeparam name="TUserId">The type of the user identifier.</typeparam>
+        /// <returns>
+        /// A converter capable of transforming the user ID to and from its string
+        /// and binary representations.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        /// Thrown if no converter has been registered for the requested user ID type.
+        /// </exception>
+        IUserIdConverter<TUserId> GetConverter<TUserId>();
+    }
+}

src/CodeBeam.UltimateAuth.Core/Abstractions/IUserIdConverterResolver.cs

@@ -0,0 +1,93 @@
+using CodeBeam.UltimateAuth.Core.Domain;
+using CodeBeam.UltimateAuth.Core.Models;
+
+namespace CodeBeam.UltimateAuth.Core.Abstractions
+{
+    /// <summary>
+    /// Provides high-level session lifecycle operations such as creation, refresh, validation, and revocation.
+    /// </summary>
+    /// <typeparam name="TUserId">The type used to uniquely identify the user.</typeparam>
+    public interface ISessionService<TUserId>
+    {
+        /// <summary>
+        /// Creates a new login session for the specified user.
+        /// </summary>
+        /// <param name="tenantId">
+        /// The tenant identifier. Use <c>null</c> for single-tenant applications.
+        /// </param>
+        /// <param name="userId">The user associated with the session.</param>
+        /// <param name="deviceInfo">Information about the device initiating the session.</param>
+        /// <param name="metadata">Optional metadata describing the session context.</param>
+        /// <param name="now">The current UTC timestamp.</param>
+        /// <returns>
+        /// A result containing the newly created session, chain, and session root.
+        /// </returns>
+        Task<SessionResult<TUserId>> CreateLoginSessionAsync(string? tenantId, TUserId userId, DeviceInfo deviceInfo, SessionMetadata? metadata, DateTime now);
+        
+        /// <summary>
+        /// Rotates the specified session and issues a new one while preserving the session chain.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="currentSessionId">The active session identifier to be refreshed.</param>
+        /// <param name="now">The current UTC timestamp.</param>
+        /// <returns>
+        /// A result containing the refreshed session and updated chain.
+        /// </returns>
+        /// <exception cref="UnauthorizedAccessException">
+        /// Thrown if the session, its chain, or the user's session root is invalid.
+        /// </exception>
+        Task<SessionResult<TUserId>> RefreshSessionAsync(string? tenantId, AuthSessionId currentSessionId,DateTime now);
+
+        /// <summary>
+        /// Revokes a single session, preventing further use.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="sessionId">The session identifier to revoke.</param>
+        /// <param name="at">The UTC timestamp of the revocation.</param>
+        Task RevokeSessionAsync(string? tenantId, AuthSessionId sessionId, DateTime at);
+
+        /// <summary>
+        /// Revokes an entire session chain (device-level logout).
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="chainId">The session chain identifier to revoke.</param>
+        /// <param name="at">The UTC timestamp of the revocation.</param>
+        Task RevokeChainAsync(string? tenantId, ChainId chainId, DateTime at);
+
+        /// <summary>
+        /// Revokes the user's session root, invalidating all existing sessions across all chains.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="userId">The user whose root should be revoked.</param>
+        /// <param name="at">The UTC timestamp of the revocation.</param>
+        Task RevokeRootAsync(string? tenantId, TUserId userId, DateTime at);
+
+        /// <summary>
+        /// Validates a session and evaluates its current state, including expiration, revocation, and security version alignment.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="sessionId">The session identifier to validate.</param>
+        /// <param name="now">The current UTC timestamp.</param>
+        /// <returns>
+        /// A detailed validation result describing the session, chain, root,
+        /// and computed session state.
+        /// </returns>
+        Task<SessionValidationResult<TUserId>> ValidateSessionAsync(string? tenantId, AuthSessionId sessionId, DateTime now);
+
+        /// <summary>
+        /// Retrieves all session chains belonging to the specified user.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="userId">The user whose session chains are requested.</param>
+        /// <returns>A read-only list of session chains.</returns>
+        Task<IReadOnlyList<ISessionChain<TUserId>>> GetChainsAsync(string? tenantId, TUserId userId);
+
+        /// <summary>
+        /// Retrieves all sessions belonging to a specific session chain.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="chainId">The session chain identifier.</param>
+        /// <returns>A read-only list of sessions contained within the chain.</returns>
+        Task<IReadOnlyList<ISession<TUserId>>> GetSessionsAsync(string? tenantId, ChainId chainId);
+    }
+}

src/CodeBeam.UltimateAuth.Core/Abstractions/Services/ISessionService.cs

@@ -0,0 +1,21 @@
+namespace CodeBeam.UltimateAuth.Core.Abstractions
+{
+    /// <summary>
+    /// Default session store factory that throws until a real store implementation is registered.
+    /// </summary>
+    public sealed class DefaultSessionStoreFactory : ISessionStoreFactory
+    {
+        /// <summary>Creates a session store instance for the given user ID type, but always throws because no store has been registered.</summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c> in single-tenant mode.</param>
+        /// <typeparam name="TUserId">The type used to uniquely identify the user.</typeparam>
+        /// <returns>Never returns; always throws.</returns>
+        /// <exception cref="InvalidOperationException">Thrown when no session store implementation has been configured.</exception>
+        public ISessionStore<TUserId> Create<TUserId>(string? tenantId)
+        {
+            throw new InvalidOperationException(
+                "No ISessionStore<TUserId> implementation registered. " +
+                "Call AddUltimateAuthServer().AddSessionStore<TStore>() to provide a real implementation."
+            );
+        }
+    }
+}

src/CodeBeam.UltimateAuth.Core/Abstractions/Stores/DefaultSessionStoreFactory.cs

@@ -0,0 +1,140 @@
+using CodeBeam.UltimateAuth.Core.Domain;
+
+namespace CodeBeam.UltimateAuth.Core.Abstractions
+{
+    /// <summary>
+    /// Defines the low-level persistence operations for sessions, session chains, and session roots in a multi-tenant or single-tenant environment.
+    /// Store implementations provide durable and atomic data access.
+    /// </summary>
+    public interface ISessionStore<TUserId>
+    {
+        /// <summary>
+        /// Retrieves a session by its identifier within the given tenant context.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c> for single-tenant mode.</param>
+        /// <param name="sessionId">The session identifier.</param>
+        /// <returns>The session instance or <c>null</c> if not found.</returns>
+        Task<ISession<TUserId>?> GetSessionAsync(string? tenantId, AuthSessionId sessionId);
+
+        /// <summary>
+        /// Persists a new session or updates an existing one within the tenant scope.
+        /// Implementations must ensure atomic writes.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="session">The session to persist.</param>
+        Task SaveSessionAsync(string? tenantId, ISession<TUserId> session);
+
+        /// <summary>
+        /// Marks the specified session as revoked, preventing future authentication.
+        /// Revocation timestamp must be stored reliably.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="sessionId">The session identifier.</param>
+        /// <param name="at">The UTC timestamp of revocation.</param>
+        Task RevokeSessionAsync(string? tenantId, AuthSessionId sessionId, DateTime at);
+        
+        /// <summary>
+        /// Returns all sessions belonging to the specified chain, ordered according to store implementation rules.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="chainId">The chain identifier.</param>
+        /// <returns>A read-only list of sessions.</returns>
+        Task<IReadOnlyList<ISession<TUserId>>> GetSessionsByChainAsync(string? tenantId, ChainId chainId);
+
+        /// <summary>
+        /// Retrieves a session chain by identifier. Returns <c>null</c> if the chain does not exist in the provided tenant context.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="chainId">The chain identifier.</param>
+        /// <returns>The chain or <c>null</c>.</returns>
+        Task<ISessionChain<TUserId>?> GetChainAsync(string? tenantId, ChainId chainId);
+
+        /// <summary>
+        /// Inserts a new session chain into the store. Implementations must ensure consistency with the related sessions and session root.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="chain">The chain to save.</param>
+        Task SaveChainAsync(string? tenantId, ISessionChain<TUserId> chain);
+
+        /// <summary>
+        /// Updates an existing session chain, typically after session rotation or revocation. Implementations must preserve atomicity.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="chain">The updated session chain.</param>
+        Task UpdateChainAsync(string? tenantId, ISessionChain<TUserId> chain);
+
+        /// <summary>
+        /// Marks the entire session chain as revoked, invalidating all associated sessions for the device or app family.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="chainId">The chain to revoke.</param>
+        /// <param name="at">The UTC timestamp of revocation.</param>
+        Task RevokeChainAsync(string? tenantId, ChainId chainId, DateTime at);
+
+        /// <summary>
+        /// Retrieves the active session identifier for the specified chain.  
+        /// This is typically an O(1) lookup and used for session rotation.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="chainId">The chain whose active session is requested.</param>
+        /// <returns>The active session identifier or <c>null</c>.</returns>
+        Task<AuthSessionId?> GetActiveSessionIdAsync(string? tenantId, ChainId chainId);
+
+        /// <summary>
+        /// Sets or replaces the active session identifier for the specified chain.
+        /// Must be atomic to prevent race conditions during refresh.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="chainId">The chain whose active session is being set.</param>
+        /// <param name="sessionId">The new active session identifier.</param>
+        Task SetActiveSessionIdAsync(string? tenantId, ChainId chainId, AuthSessionId sessionId);
+
+        /// <summary>
+        /// Retrieves all session chains belonging to the specified user within the tenant scope.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="userId">The user whose chains are being retrieved.</param>
+        /// <returns>A read-only list of session chains.</returns>
+        Task<IReadOnlyList<ISessionChain<TUserId>>> GetChainsByUserAsync(string? tenantId, TUserId userId);
+
+        /// <summary>
+        /// Retrieves the session root for the user, which represents the full set of chains and their associated security metadata.
+        /// Returns <c>null</c> if the root does not exist.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="userId">The user identifier.</param>
+        /// <returns>The session root or <c>null</c>.</returns>
+        Task<ISessionRoot<TUserId>?> GetSessionRootAsync(string? tenantId, TUserId userId);
+
+        /// <summary>
+        /// Persists a session root structure, usually after chain creation, rotation, or security operations.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="root">The session root to save.</param>
+        Task SaveSessionRootAsync(string? tenantId, ISessionRoot<TUserId> root);
+
+        /// <summary>
+        /// Revokes the session root, invalidating all chains and sessions belonging to the specified user in the tenant scope.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="userId">The user whose root should be revoked.</param>
+        /// <param name="at">The UTC timestamp of revocation.</param>
+        Task RevokeSessionRootAsync(string? tenantId, TUserId userId, DateTime at);
+
+        /// <summary>
+        /// Removes expired sessions from the store while leaving chains and session roots intact. Cleanup strategy is determined by the store implementation.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="now">The current UTC timestamp.</param>
+        Task DeleteExpiredSessionsAsync(string? tenantId, DateTime now);
+
+        /// <summary>
+        /// Retrieves the chain identifier associated with the specified session.
+        /// </summary>
+        /// <param name="tenantId">The tenant identifier, or <c>null</c>.</param>
+        /// <param name="sessionId">The session identifier.</param>
+        /// <returns>The chain identifier or <c>null</c>.</returns>
+        Task<ChainId?> GetChainIdBySessionAsync(string? tenantId, AuthSessionId sessionId);
+    }
+
+}

src/CodeBeam.UltimateAuth.Core/Abstractions/Stores/ISessionStore.cs

@@ -0,0 +1,25 @@
+namespace CodeBeam.UltimateAuth.Core.Abstractions
+{
+    /// <summary>
+    /// Provides a factory abstraction for creating tenant-scoped session store
+    /// instances capable of persisting sessions, chains, and session roots.
+    /// Implementations typically resolve concrete <see cref="ISessionStore{TUserId}"/> types from the dependency injection container.
+    /// </summary>
+    public interface ISessionStoreFactory
+    {
+        /// <summary>
+        /// Creates and returns a session store instance for the specified user ID type within the given tenant context.
+        /// </summary>
+        /// <typeparam name="TUserId">The type used to uniquely identify users.</typeparam>
+        /// <param name="tenantId">
+        /// The tenant identifier for multi-tenant environments, or <c>null</c> for single-tenant mode.
+        /// </param>
+        /// <returns>
+        /// An <see cref="ISessionStore{TUserId}"/> implementation able to perform session persistence operations.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        /// Thrown if no compatible session store implementation is registered.
+        /// </exception>
+        ISessionStore<TUserId> Create<TUserId>(string? tenantId);
+    }
+}