littlefish_auth 1.0.4

A littlefish package for authentication and session management.

Littlefish Auth

A robust authentication and session management package designed for the Littlefish ecosystem. This package implements a multi-token architecture that separates Identity Provider authentication (Access Tokens) from internal application authorization (Session Tokens), enabling seamless user switching capabilities without requiring full re-authentication.

🏗 Architecture Overview

The core design philosophy of littlefish_auth distinguishes between Authentication (Who you are) and Session/Authorization (Which "room" you are in).

The Multi-Token Concept

• Access Token ("Keys to the House"):
  • Provided by the external Identity Provider (e.g., Firebase).
  • Establishes the identity of the physical user/device owner.
  • Used to authenticate calls to the Session Microservice as well as to the merchant API in the authorization header.
• Session Token ("Keys to the Room"):
  • Issued by the Littlefish Session Microservice.
  • Contains granular claims and information specific to the current context (e.g., Admin vs. Waiter).
  • Used for all business logic API requests.

User Switching

This architecture allows a device to maintain a single verified connection to the Identity Provider (Access Token) while managing multiple user sessions locally.

• Scenario: An Admin logs in (Access Token acquired).
• Action: A waiter wants to use the POS. They enter a PIN.
• Result: The AuthSession is switched. The Access Token remains the same, but the Session Token is swapped. The device is now acting as the Waiter without a network-heavy logout/login process.

🧩 Key Components

1. LittlefishAuthManager

The primary entry point (Facade) for the application. It orchestrates the interaction between the AuthService (Identity Provider) and the SessionManager.

• Handles Sign In/Sign Out (Firebase/OAuth).
• Exposes current AuthUser and AuthSession.
• Delegates session switching logic.

2. SessionManager

Responsible for the lifecycle of a session.

• Create: Fetches new session tokens from the backend.
• Refresh: Handles token expiration and auto-refresh logic.
• Switch: Swaps the active user session stored in memory/storage.
• Validate: Ensures tokens are not expired using JwtTokenHelper.

3. LocalSessionRepository

Manages the local persistence of sessions.

• Memory: Keeps active sessions available for instant switching.
• Secure Storage: Persists session tokens encrypted on the device to survive app restarts.
• Index: Maintains a list of known users on the device.

4. MerchantSessionService

The networking layer that communicates with the Session Microservice.

• Injects X-Device-Id and AuthUser headers.
• Performs CRUD operations for sessions.

---

🚀 Getting Started

Prerequisites

This package relies on littlefish_core for dependency injection, logging, and configuration. Ensure LittleFishCore is initialized before using this package.