/**
 * tokenInterface - Interface defining authentication token structure
 *
 * This interface represents the standard structure of authentication tokens
 * returned by OAuth 2.0 compliant authentication systems. It follows
 * established patterns for token-based authentication with support for
 * both access and refresh tokens.
 *
 * The interface is minimal and focused, containing only the essential
 * token properties needed for most authentication flows. It's designed
 * to be used across the application for consistent token handling.
 *
 * @see https://datatracker.ietf.org/doc/html/rfc6749 - OAuth 2.0 Framework
 * @see https://datatracker.ietf.org/doc/html/rfc6750 - Bearer Token Usage
 *
 * @example
 * // Typical token response
 * const tokens: tokenInterface = {
 *   access_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
 *   refresh_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
 *   expires_in: 3600
 * };
 *
 * @example
 * // Usage in service methods
 * async login(credentials: Credentials): Promise<tokenInterface> {
 *   const user = await this.validateUser(credentials);
 *   return {
 *     access_token: this.jwtService.sign({ sub: user.id }),
 *     refresh_token: this.jwtService.sign({ sub: user.id }, { expiresIn: '7d' }),
 *     expires_in: 3600
 *   };
 * }
 */
export interface tokenInterface {
  /**
   * Access token (JWT)
   *
   * The primary short-lived token used to access protected resources.
   * Typically a JSON Web Token (JWT) that contains user claims and permissions.
   *
   * Characteristics:
   * - Short lifetime (minutes to hours)
   * - Contains user identity and authorization claims
   * - Used in Authorization header: `Bearer {access_token}`
   * - Signed to prevent tampering
   * - May include scopes/permissions
   *
   * Security best practices:
   * - Use strong signing algorithms (RS256, HS256)
   * - Keep payload minimal to reduce token size
   * - Include standard JWT claims (iss, sub, aud, exp, iat)
   * - Never store sensitive data in token
   * - Validate token on every protected request
   *
   * @example "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
   * @example "ya29.a0AfH6SMBw..."
   */
  access_token: string;

  /**
   * Refresh token
   *
   * Long-lived token used to obtain new access tokens without requiring
   * user credentials. Enables persistent sessions while maintaining security.
   *
   * Characteristics:
   * - Long lifetime (days to months)
   * - Stored securely by client application
   * - Single-use or limited-use to prevent replay attacks
   * - Can be revoked independently of access token
   * - Used only at token refresh endpoint
   *
   * Security considerations:
   * - Store in HTTP-only, secure cookies for web applications
   * - Implement token rotation (issue new refresh token on each use)
   * - Track usage for anomaly detection
   * - Allow user-initiated revocation
   * - Consider refresh token expiration for inactive accounts
   *
   * @note Some implementations may make this optional for certain grant types
   *
   * @example "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
   * @example "1//03abcdefghijkl..."
   */
  refresh_token: string;

  /**
   * Access token expiration in seconds
   *
   * Specifies the lifetime of the access token in seconds from issuance time.
   * Helps clients manage token refresh cycles and implement proper caching.
   *
   * Common values:
   * - 300 (5 minutes): High security applications, banking
   * - 1800 (30 minutes): Balanced security/convenience
   * - 3600 (1 hour): Standard web applications
   * - 86400 (24 hours): Long-lived sessions (with refresh tokens)
   *
   * Implementation notes:
   * - Should be consistent with the `exp` claim in the JWT
   * - Consider shorter lifetimes for sensitive operations
   * - Use refresh tokens to maintain sessions without frequent logins
   * - May vary based on user role or security requirements
   *
   * @example 3600
   * @example 86400
   */
  expires_in: number;
}
