pec_ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 81169a18f557a07493e4dc4dd5d1daee96638209bcd95cca4e79d3d8b1e6fe70
+  data.tar.gz: d84b84c4e2f75fcad73bbf8987dfe83ba9ff7d2997e5bda9a50117977b5096c4
+SHA512:
+  metadata.gz: b3eed5f566866056fa6fe9ac1bb5aa4d6698cd16ae6f56534ac8f63bdc307df5aa948f521765061d90963ba3284ec9d7583218fb9e5d2814a790fa18c97a8603
+  data.tar.gz: 44a1840dbb4cd1feb585cab2ca2e2ca81b403b5154dca1408553cb9001790877d445460b2a1df7c4286bb1f373197a4a508f2d3970c3ef9aa2c63e223f9567d6

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-07-13
+
+### Added
+- Initial release of PecRuby gem
+- IMAP client for connecting to Italian PEC servers
+- Automatic extraction of postacert.eml attachments
+- Message parsing and decoding functionality
+- Attachment management with download capabilities
+- Command-line interface (CLI) for interactive exploration
+- Comprehensive error handling
+- Support for flexible installation (with/without CLI dependencies)
+- Complete API documentation
+- Example usage files
+
+### Features
+- **PecRuby::Client**: Main client class for IMAP operations
+- **PecRuby::Message**: Message representation with original content extraction
+- **PecRuby::Attachment**: Attachment handling with save capabilities
+- **PecRuby::CLI**: Interactive command-line interface
+- **Error Classes**: Specific error types for better error handling
+- **Flexible Dependencies**: Optional CLI dependencies for minimal installations
+
+### Supported Providers
+- Aruba PEC (imaps.pec.aruba.it)
+- Generic IMAP-compliant PEC providers
+
+[Unreleased]: https://github.com/egio12/pec_ruby/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/egio12/pec_ruby/releases/tag/v0.1.0

data/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rubocop", "~> 1.21"

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 EMG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,364 @@
+# PecRuby
+
+A comprehensive Ruby gem for decoding and managing Italian PEC (Posta Elettronica Certificata) email messages.
+
+## Features
+
+- **IMAP Connection**: Connect to Italian PEC servers
+- **Automatic Extraction**: Automatically extracts original messages from postacert.eml attachments
+- **Attachment Management**: Download and manage attachments easily
+- **CLI Included**: Command-line interface for exploring PEC messages
+- **Programmatic API**: Methods for integrating PEC functionality into your Ruby applications
+
+## Installation
+
+### Library Only (without CLI)
+
+To use only the programmatic API without the command-line interface:
+
+```ruby
+gem 'pec_ruby'
+```
+
+Or install directly:
+
+```bash
+gem install pec_ruby
+```
+
+### With CLI Included
+
+To also use the command-line interface, install additional dependencies:
+
+```bash
+gem install pec_ruby tty-prompt awesome_print
+```
+
+Or in your Gemfile:
+
+```ruby
+gem 'pec_ruby'
+gem 'tty-prompt', '~> 0.23'
+gem 'awesome_print', '~> 1.9'
+```
+
+## CLI Usage
+
+After complete installation (with CLI dependencies), you can use the CLI:
+
+```bash
+pec_ruby
+```
+
+**Note**: If you installed only the library without CLI dependencies, the `pec_ruby` executable will inform you how to install them.
+
+The CLI allows you to:
+- Connect to your PEC server
+- Explore received messages
+- View decoded original message contents
+- Download attachments
+
+## Programmatic Usage
+
+### Basic Connection
+
+```ruby
+require 'pec_ruby'
+
+# Connect to PEC server
+client = PecRuby::Client.new(
+  host: 'imaps.pec.aruba.it',
+  username: 'your@domain.pec.it', 
+  password: 'password'
+)
+
+client.connect
+```
+
+### Retrieving Messages
+
+```ruby
+# All messages (last 10)
+messages = client.messages(limit: 10)
+
+# Only PEC messages (with postacert.eml)
+pec_messages = client.pec_messages(limit: 10)
+
+# Specific message by UID
+message = client.message(12345)
+```
+
+### Working with Messages
+
+```ruby
+message = client.pec_messages.first
+
+# PEC container information
+puts message.subject        # PEC message subject
+puts message.from          # PEC sender
+puts message.date          # PEC message date
+
+# Original message information
+puts message.original_subject  # Original subject
+puts message.original_from    # Original sender
+puts message.original_body    # Original message body
+
+# Attachments
+message.original_attachments.each do |attachment|
+  puts "#{attachment.filename} (#{attachment.size_kb} KB)"
+  
+  # Save attachment
+  attachment.save_to("/path/to/file.pdf")
+  # or
+  attachment.save_to_dir("/downloads/")
+end
+```
+
+## API Documentation
+
+### PecRuby::Client
+
+The main client class for connecting to PEC servers.
+
+#### Constructor
+
+```ruby
+PecRuby::Client.new(host:, username:, password:, ssl: true)
+```
+
+**Parameters:**
+- `host` (String): IMAP server hostname
+- `username` (String): PEC email address
+- `password` (String): Account password
+- `ssl` (Boolean): Use SSL connection (default: true)
+
+#### Instance Methods
+
+##### `#connect`
+Establishes connection to the PEC server.
+
+```ruby
+client.connect
+# Returns: self
+# Raises: PecRuby::ConnectionError, PecRuby::AuthenticationError
+```
+
+##### `#disconnect`
+Safely disconnects from the PEC server.
+
+```ruby
+client.disconnect
+# Returns: nil
+```
+
+##### `#connected?`
+Checks if currently connected to the server.
+
+```ruby
+client.connected?
+# Returns: Boolean
+```
+
+##### `#messages(limit: nil, reverse: true)`
+Retrieves messages from the server.
+
+```ruby
+messages = client.messages(limit: 10, reverse: true)
+# Returns: Array<PecRuby::Message>
+```
+
+**Parameters:**
+- `limit` (Integer, optional): Maximum number of messages to retrieve
+- `reverse` (Boolean): Return newest messages first (default: true)
+
+##### `#pec_messages(limit: nil, reverse: true)`
+Retrieves only messages containing postacert.eml.
+
+```ruby
+pec_messages = client.pec_messages(limit: 5)
+# Returns: Array<PecRuby::Message>
+```
+
+##### `#message(uid)`
+Retrieves a specific message by UID.
+
+```ruby
+message = client.message(12345)
+# Returns: PecRuby::Message or nil
+```
+
+### PecRuby::Message
+
+Represents a PEC message with access to both container and original message data.
+
+#### Instance Methods
+
+##### Basic PEC Container Information
+
+```ruby
+# PEC envelope information
+message.uid            # Integer: Message UID
+message.subject        # String: PEC subject (cleaned)
+message.from           # String: PEC sender
+message.to             # Array<String>: PEC recipients
+message.date           # Time: PEC message date
+```
+
+##### Original Message Access
+
+```ruby
+# Check if postacert.eml is available
+message.has_postacert?    # Boolean
+
+# Original message information
+message.original_subject  # String: Original subject
+message.original_from     # String: Original sender
+message.original_to       # Array<String>: Original recipients
+message.original_date     # Time: Original message date
+message.original_body     # String: Original message body (decoded)
+```
+
+##### Attachments
+
+```ruby
+# Get original message attachments
+message.original_attachments  # Array<PecRuby::Attachment>
+```
+
+##### Summary Information
+
+```ruby
+# Get complete message summary
+summary = message.summary
+# Returns: Hash with all message information
+```
+
+### PecRuby::Attachment
+
+Represents an attachment from the original message.
+
+#### Instance Methods
+
+```ruby
+# Basic information
+attachment.filename     # String: Original filename
+attachment.mime_type    # String: MIME type
+attachment.size         # Integer: Size in bytes
+attachment.size_kb      # Float: Size in KB
+attachment.size_mb      # Float: Size in MB
+
+# Content access
+attachment.content      # String: Raw binary content
+
+# File operations
+attachment.save_to(path)           # Save to specific path
+attachment.save_to_dir(directory)  # Save to directory with original filename
+
+# Summary
+attachment.summary      # Hash: Complete attachment information
+attachment.to_s         # String: Human-readable description
+```
+
+## Complete Example
+
+```ruby
+require 'pec_ruby'
+
+begin
+  # Connect
+  client = PecRuby::Client.new(
+    host: 'imaps.pec.aruba.it',
+    username: 'example@pec.it',
+    password: 'password'
+  )
+  client.connect
+
+  # Get last 5 PEC messages
+  pec_messages = client.pec_messages(limit: 5)
+  
+  pec_messages.each do |message|
+    puts "Subject: #{message.original_subject}"
+    puts "From: #{message.original_from}"
+    puts "Attachments: #{message.original_attachments.size}"
+    
+    # Download attachments
+    message.original_attachments.each do |attachment|
+      attachment.save_to_dir('./downloads')
+      puts "Downloaded: #{attachment.filename}"
+    end
+    
+    puts "─" * 40
+  end
+
+ensure
+  client&.disconnect
+end
+```
+
+## Error Handling
+
+The gem defines several specific error classes:
+
+```ruby
+PecRuby::Error                 # Base error class
+PecRuby::ConnectionError       # Connection issues
+PecRuby::AuthenticationError   # Login failures
+PecRuby::MessageNotFoundError  # Message not found
+PecRuby::PostacertNotFoundError # postacert.eml not found
+```
+
+Example with error handling:
+
+```ruby
+begin
+  client = PecRuby::Client.new(...)
+  client.connect
+rescue PecRuby::AuthenticationError => e
+  puts "Login failed: #{e.message}"
+rescue PecRuby::ConnectionError => e
+  puts "Connection error: #{e.message}"
+rescue PecRuby::Error => e
+  puts "PEC error: #{e.message}"
+end
+```
+
+## Supported PEC Providers
+
+The gem has been tested with:
+- Aruba PEC (`imaps.pec.aruba.it`) ✅ **Fully tested**
+
+Other providers should work if they support standard IMAP, but have not been tested yet.
+
+## Current Limitations
+
+- **Message Threading**: The gem currently does not support message threading or conversation grouping. Each message is handled individually.
+- **Provider Testing**: Only tested with Aruba PEC. Other providers may work but are not guaranteed.
+- **Legal Compliance**: This library has not been evaluated for compliance with Italian PEC regulations or legal requirements. The message parsing methods used may not preserve all legally required aspects of certified email messages. Users should consult with legal experts and review applicable regulations before using this library in legally sensitive contexts.
+
+## Development
+
+After cloning the repository:
+
+```bash
+bundle install
+bundle exec rspec          # Run tests
+bundle exec rubocop        # Check code style
+```
+
+## Contributing
+
+1. Fork the project
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+## Contact
+
+Enrico Giordano - enricomaria.giordano@icloud.com
+
+Project Link: [https://github.com/egio12/pec_ruby](https://github.com/egio12/pec_ruby)

data/bin/pec_ruby

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/pec_ruby'
+
+begin
+  if defined?(PecRuby::CLI)
+    PecRuby::CLI.new.run
+  else
+    puts "CLI non disponibile. Installa le dipendenze CLI:"
+    puts "gem install tty-prompt awesome_print"
+    exit 1
+  end
+rescue LoadError => e
+  puts "Errore nel caricamento della CLI: #{e.message}"
+  puts "Installa le dipendenze CLI:"
+  puts "gem install tty-prompt awesome_print"
+  exit 1
+end

data/lib/pec_ruby/attachment.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module PecRuby
+  class Attachment
+    attr_reader :mail_attachment
+
+    def initialize(mail_attachment)
+      @mail_attachment = mail_attachment
+    end
+
+    def filename
+      @mail_attachment.filename || "unnamed_file"
+    end
+
+    def mime_type
+      @mail_attachment.mime_type || "application/octet-stream"
+    end
+
+    def size
+      content.bytesize
+    end
+
+    def size_kb
+      (size / 1024.0).round(1)
+    end
+
+    def size_mb
+      (size / 1024.0 / 1024.0).round(2)
+    end
+
+    def content
+      @mail_attachment.decoded
+    end
+
+    # Save attachment to file
+    def save_to(path)
+      File.binwrite(path, content)
+    end
+
+    # Save attachment to directory with original filename
+    def save_to_dir(directory)
+      path = File.join(directory, filename)
+      save_to(path)
+      path
+    end
+
+    def summary
+      {
+        filename: filename,
+        mime_type: mime_type,
+        size: size,
+        size_kb: size_kb,
+        size_mb: size_mb
+      }
+    end
+
+    def to_s
+      "#{filename} (#{mime_type}, #{size_kb} KB)"
+    end
+  end
+end

data/lib/pec_ruby/cli.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+begin
+  require 'tty-prompt'
+  require 'awesome_print'
+rescue LoadError => e
+  raise LoadError, "CLI dependencies not available. Install with: gem install tty-prompt awesome_print"
+end
+
+module PecRuby
+  class CLI
+    def initialize
+      @client = nil
+      @prompt = TTY::Prompt.new
+    end
+
+    def run
+      puts banner
+      
+      loop do
+        case main_menu
+        when :connect
+          connect_to_server
+        when :list_messages
+          list_and_select_messages if connected?
+        when :disconnect
+          disconnect_from_server
+        when :exit
+          disconnect_from_server if connected?
+          puts "\nArrivederci!"
+          break
+        end
+      end
+    end
+
+    private
+
+    def banner
+      <<~BANNER
+        
+        ╔═══════════════════════════════════════════════════════════════╗
+        ║                       PEC Decoder CLI                        ║
+        ║               Decodificatore PEC per Ruby                     ║
+        ╚═══════════════════════════════════════════════════════════════╝
+        
+      BANNER
+    end
+
+    def main_menu
+      choices = []
+      
+      if connected?
+        choices << { name: "Lista e analizza messaggi PEC", value: :list_messages }
+        choices << { name: "Disconnetti dal server", value: :disconnect }
+      else
+        choices << { name: "Connetti al server PEC", value: :connect }
+      end
+      
+      choices << { name: "Esci", value: :exit }
+
+      @prompt.select("Seleziona un'azione:", choices)
+    end
+
+    def connect_to_server
+      return if connected?
+
+      puts "\nCONNESSIONE AL SERVER PEC"
+      puts "─" * 40
+
+      host = @prompt.ask("Host IMAP:", default: "imaps.pec.aruba.it")
+      username = @prompt.ask("Username/Email:")
+      password = @prompt.mask("Password:")
+
+      print "Connessione in corso..."
+      
+      begin
+        @client = Client.new(host: host, username: username, password: password)
+        @client.connect
+        puts " Connesso!"
+        puts "Connesso come: #{@client.username}"
+      rescue PecRuby::Error => e
+        puts " Errore!"
+        puts "ATTENZIONE: #{e.message}"
+        @client = nil
+      end
+    end
+
+    def connected?
+      @client&.connected?
+    end
+
+    def disconnect_from_server
+      return unless connected?
+      
+      @client.disconnect
+      @client = nil
+      puts "Disconnesso dal server"
+    end
+
+    def list_and_select_messages
+      puts "\nCaricamento messaggi..."
+      
+      begin
+        messages = @client.pec_messages(limit: 20, reverse: true)
+        
+        if messages.empty?
+          puts "Nessun messaggio PEC trovato"
+          return
+        end
+
+        choices = messages.map do |msg|
+          label = format_message_label(msg)
+          [label, msg]
+        end
+
+        puts "\n" + "─" * 120
+        puts "MESSAGGI PEC RICEVUTI (più recenti in alto)"
+        puts "─" * 120
+        
+        selected_message = @prompt.select("Seleziona un messaggio:", choices.to_h, per_page: 15, cycle: true)
+        display_message(selected_message)
+        
+      rescue PecRuby::Error => e
+        puts "Errore nel recupero messaggi: #{e.message}"
+      end
+    end
+
+    def format_message_label(message)
+      subject = message.subject || "(nessun oggetto)"
+      from = message.from || "(mittente sconosciuto)"
+      date = message.date ? message.date.strftime("%d/%m %H:%M") : "N/A"
+      
+      short_subject = subject.length > 60 ? "#{subject[0..56]}..." : subject
+      
+      sprintf("%-60s | %-25s | %s", 
+             short_subject, 
+             from.to_s[0..24], 
+             date)
+    end
+
+    def display_message(message)
+      puts "\n" + "="*80
+      puts "MESSAGGIO PEC DECODIFICATO"
+      puts "="*80
+
+      # Informazioni base PEC
+      puts "\nINFORMAZIONI CONTENITORE PEC"
+      puts "─"*50
+      puts sprintf("Oggetto PEC: %s", message.subject || "(nessun oggetto)")
+      puts sprintf("From PEC:    %s", message.from || "(sconosciuto)")
+      puts sprintf("Data PEC:    %s", message.date ? message.date.strftime("%d/%m/%Y %H:%M") : "(sconosciuta)")
+
+      # Informazioni messaggio originale
+      if message.has_postacert?
+        puts "\nMESSAGGIO ORIGINALE (da postacert.eml)"
+        puts "─"*50
+        puts sprintf("Oggetto:     %s", message.original_subject || "(nessun oggetto)")
+        puts sprintf("Mittente:    %s", message.original_from || "(sconosciuto)")
+        puts sprintf("Destinatari: %s", message.original_to.join(', '))
+        puts sprintf("Data:        %s", message.original_date ? message.original_date.strftime("%d/%m/%Y %H:%M") : "(sconosciuta)")
+
+        # Corpo del messaggio
+        body = message.original_body
+        if body && !body.strip.empty?
+          puts "\nCORPO DEL MESSAGGIO"
+          puts "─"*50
+          puts body.strip
+        end
+
+        # Allegati
+        attachments = message.original_attachments
+        puts "\nALLEGATI"
+        puts "─"*50
+        if attachments.any?
+          attachments.each_with_index do |att, i|
+            puts sprintf("%d. %-30s | %s | %.1f KB", 
+                        i+1, 
+                        att.filename, 
+                        att.mime_type,
+                        att.size_kb)
+          end
+          
+          if @prompt.yes?("\nVuoi scaricare gli allegati?")
+            download_attachments(attachments)
+          end
+        else
+          puts "   Nessun allegato presente"
+        end
+      else
+        puts "\nATTENZIONE: Questo messaggio non contiene postacert.eml"
+      end
+      
+      puts "\n" + "="*80
+      @prompt.keypress("\nPremi un tasto per continuare...")
+    end
+
+    def download_attachments(attachments)
+      download_dir = @prompt.ask("Directory di download:", default: "./downloads")
+      
+      begin
+        require 'fileutils'
+        FileUtils.mkdir_p(download_dir)
+        
+        attachments.each do |attachment|
+          file_path = attachment.save_to_dir(download_dir)
+          puts "Salvato: #{file_path}"
+        end
+        
+        puts "Tutti gli allegati sono stati salvati in #{download_dir}"
+      rescue => e
+        puts "Errore nel salvataggio: #{e.message}"
+      end
+    end
+  end
+end

data/lib/pec_ruby/client.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'net/imap'
+require 'mail'
+
+module PecRuby
+  class Client
+    attr_reader :imap, :host, :username
+
+    def initialize(host:, username:, password:, ssl: true)
+      @host = host
+      @username = username
+      @password = password
+      @ssl = ssl
+      @imap = nil
+    end
+
+    def connect
+      @imap = Net::IMAP.new(@host, ssl: @ssl)
+      authenticate
+      select_inbox
+      self
+    rescue Net::IMAP::Error => e
+      raise ConnectionError, "Failed to connect to #{@host}: #{e.message}"
+    end
+
+    def disconnect
+      return unless @imap
+
+      begin
+        @imap.logout if @imap && !@imap.disconnected?
+      rescue => e
+        # Ignore logout errors if connection is already closed
+      end
+      
+      begin
+        @imap.disconnect if @imap && !@imap.disconnected?
+      rescue => e
+        # Ignore disconnect errors if connection is already closed
+      end
+      
+      @imap = nil
+    end
+
+    def connected?
+      @imap && !@imap.disconnected?
+    end
+
+    # Get all messages or a subset
+    def messages(limit: nil, reverse: true)
+      raise ConnectionError, "Not connected" unless connected?
+      
+      sequence_numbers = @imap.search(['ALL'])
+      sequence_numbers = sequence_numbers.reverse if reverse
+      sequence_numbers = sequence_numbers.first(limit) if limit
+      
+      fetch_messages(sequence_numbers)
+    end
+
+    # Get a specific message by UID
+    def message(uid)
+      raise ConnectionError, "Not connected" unless connected?
+      
+      fetch_data = @imap.uid_fetch(uid, ["UID", "ENVELOPE", "BODYSTRUCTURE"])
+      return nil if fetch_data.nil? || fetch_data.empty?
+      
+      Message.new(self, fetch_data.first)
+    end
+
+    # Get messages with postacert.eml only
+    def pec_messages(limit: nil, reverse: true)
+      messages(limit: limit, reverse: reverse).select(&:has_postacert?)
+    end
+
+    # Internal method to fetch message body parts
+    def fetch_body_part(uid, part_id)
+      @imap.uid_fetch(uid, "BODY[#{part_id}]")[0].attr["BODY[#{part_id}]"]
+    end
+
+    private
+
+    def authenticate
+      @imap.authenticate("PLAIN", @username, @password)
+    rescue Net::IMAP::Error => e
+      raise AuthenticationError, "Authentication failed: #{e.message}"
+    end
+
+    def select_inbox
+      @imap.select('INBOX')
+    end
+
+    def fetch_messages(sequence_numbers)
+      return [] if sequence_numbers.empty?
+      
+      messages_data = @imap.fetch(sequence_numbers, ["UID", "ENVELOPE", "BODYSTRUCTURE"])
+      messages_data.map { |msg_data| Message.new(self, msg_data) }
+    end
+  end
+end

data/lib/pec_ruby/message.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'mail'
+
+module PecRuby
+  class Message
+    attr_reader :uid, :envelope, :bodystructure, :client
+
+    def initialize(client, fetch_data)
+      @client = client
+      @uid = fetch_data.attr["UID"]
+      @envelope = fetch_data.attr["ENVELOPE"]
+      @bodystructure = fetch_data.attr["BODYSTRUCTURE"]
+      @postacert_mail = nil
+      @postacert_extracted = false
+    end
+
+    # Basic envelope information
+    def subject
+      return nil unless @envelope.subject
+      
+      decoded = Mail::Encodings.value_decode(@envelope.subject)
+      decoded.gsub!("POSTA CERTIFICATA:", "") if decoded.start_with?("POSTA CERTIFICATA:")
+      decoded.strip
+    end
+
+    def from
+      return nil unless @envelope.from&.first
+      
+      from_addr = @envelope.from.first
+      extract_real_sender(from_addr)
+    end
+
+    def to
+      return [] unless @envelope.to
+      
+      @envelope.to.map { |addr| "#{addr.mailbox}@#{addr.host}" }
+    end
+
+    def date
+      @envelope.date ? Time.parse(@envelope.date.to_s) : nil
+    end
+
+    # Check if message contains postacert.eml
+    def has_postacert?
+      !find_postacert_part_ids.empty?
+    end
+
+    # Extract and return the original message from postacert.eml
+    def postacert_message
+      return @postacert_mail if @postacert_extracted
+      
+      @postacert_extracted = true
+      part_ids = find_postacert_part_ids
+      
+      if part_ids.empty?
+        @postacert_mail = nil
+        return nil
+      end
+
+      begin
+        part_id = part_ids.first
+        raw_data = @client.fetch_body_part(@uid, part_id)
+        @postacert_mail = Mail.read_from_string(raw_data)
+      rescue => e
+        raise Error, "Failed to extract postacert.eml: #{e.message}"
+      end
+
+      @postacert_mail
+    end
+
+    # Get original message subject
+    def original_subject
+      postacert_message&.subject
+    end
+
+    # Get original message sender
+    def original_from
+      postacert_message&.from&.first
+    end
+
+    # Get original message recipients
+    def original_to
+      postacert_message&.to || []
+    end
+
+    # Get original message date
+    def original_date
+      postacert_message&.date
+    end
+
+    # Get original message body (text/plain preferred)
+    def original_body
+      mail = postacert_message
+      return nil unless mail
+
+      text_part = extract_text_part(mail, "text/plain")
+      html_part = extract_text_part(mail, "text/html")
+      selected_part = text_part || html_part
+
+      return nil unless selected_part
+
+      raw_body = selected_part.body.decoded
+      charset = selected_part.charset || 
+                selected_part.content_type_parameters&.[]("charset") || 
+                "UTF-8"
+      
+      raw_body.force_encoding(charset).encode("UTF-8")
+    end
+
+    # Get original message attachments
+    def original_attachments
+      mail = postacert_message
+      return [] unless mail&.attachments
+
+      mail.attachments.map { |att| Attachment.new(att) }
+    end
+
+    # Summary information
+    def summary
+      {
+        uid: @uid,
+        subject: subject,
+        from: from,
+        to: to,
+        date: date,
+        has_postacert: has_postacert?,
+        original_subject: original_subject,
+        original_from: original_from,
+        original_to: original_to,
+        original_date: original_date,
+        attachments_count: original_attachments.size
+      }
+    end
+
+    private
+
+    def extract_real_sender(from_addr)
+      email = "#{from_addr.mailbox}@#{from_addr.host}"
+      
+      # Handle "Per conto di:" in name field
+      if from_addr.name&.include?("Per conto di:")
+        email_match = from_addr.name.match(/([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/)
+        return email_match[1] if email_match
+      elsif from_addr.name && !from_addr.name.include?("posta-certificata@")
+        return from_addr.name
+      end
+      
+      email
+    end
+
+    def find_postacert_part_ids(bodystructure = @bodystructure, path = "")
+      results = []
+
+      if bodystructure.respond_to?(:parts) && bodystructure.parts
+        bodystructure.parts.each_with_index do |part, index|
+          part_path = path.empty? ? "#{index + 1}" : "#{path}.#{index + 1}"
+          results += find_postacert_part_ids(part, part_path)
+        end
+      elsif bodystructure.media_type == "MESSAGE" && bodystructure.subtype == "RFC822"
+        if bodystructure.param && bodystructure.param["NAME"]&.downcase&.include?("postacert.eml")
+          results << path
+        end
+      end
+
+      results
+    end
+
+    def extract_text_part(mail, preferred_type = "text/plain")
+      return mail unless mail.multipart?
+
+      mail.parts.each do |part|
+        if part.multipart?
+          found = extract_text_part(part, preferred_type)
+          return found if found
+        elsif part.mime_type == preferred_type
+          return part
+        end
+      end
+
+      nil
+    end
+  end
+end

data/lib/pec_ruby/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PecRuby
+  VERSION = "0.1.0"
+end

data/lib/pec_ruby.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "pec_ruby/version"
+require_relative "pec_ruby/client"
+require_relative "pec_ruby/message"
+require_relative "pec_ruby/attachment"
+
+# CLI is optional - only load if dependencies are available
+begin
+  require_relative "pec_ruby/cli"
+rescue LoadError
+  # CLI dependencies not available - skip CLI functionality
+end
+
+module PecRuby
+  class Error < StandardError; end
+  class ConnectionError < Error; end
+  class AuthenticationError < Error; end
+  class MessageNotFoundError < Error; end
+  class PostacertNotFoundError < Error; end
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: pec_ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- EMG
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-07-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: net-imap
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A comprehensive Ruby library for handling Italian certified email (PEC)
+  messages. Includes methods for extracting postacert.eml contents, decoding attachments,
+  and a CLI for exploring PEC messages.
+email:
+- enricomaria.giordano@icloud.com
+executables:
+- pec_ruby
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- bin/pec_ruby
+- lib/pec_ruby.rb
+- lib/pec_ruby/attachment.rb
+- lib/pec_ruby/cli.rb
+- lib/pec_ruby/client.rb
+- lib/pec_ruby/message.rb
+- lib/pec_ruby/version.rb
+homepage: https://github.com/egio12/pec_ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/egio12/pec_ruby
+  source_code_uri: https://github.com/egio12/pec_ruby
+  changelog_uri: https://github.com/egio12/pec_ruby/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby gem for decoding and reading Italian PEC (Posta Elettronica Certificata)
+  emails
+test_files: []