wsaa-ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 398c92ee7bbeb19908d73033e371a8ee15c20e981eb377b26eccfa260d51c410
-  data.tar.gz: 7396411b2096967bd3113d77357b91c92bf64c41cc673993aa74bf2b1843ffd1
+  metadata.gz: 708f1b5afef609eb4e0dfde437af7905f84db50ac5ae910aa6cb6e0af0253864
+  data.tar.gz: 25dba3b78a08508479cdf2a4fb1485011ef1cb5083ee490683f4b06199ee90f9
 SHA512:
-  metadata.gz: 0335726e838104a2738869286ff3da6e5ec5fc128d8ea3f23094c624b9ccbcf95363cdb09502097210fa970fbe1fc86b618058be773e780c84afff45e57dbec0
-  data.tar.gz: 79beb07a9f78bc8ff61ae4e8f2d6508417de9903e02c92c835e998710035b7a36a09d3e00a5d0a88b6fac9cb05c7e64fec1e1877369edf00b34658810451ad44
+  metadata.gz: 3c3f0bfa7e1abec8065f1f1bec28a28e51adc9ed0fc61a602927286d3bd74c28c075427d06c4a2b4b3d81a4e82a3de405d6c31ab33b02f9a17d92837090d9294
+  data.tar.gz: 73f8b5adeb3313515cc713f0a679798d583e8fb96dc9d5693ec1b870bd6b737588b6763255f212a1f6fd7591df2c7d9ad539a277627ed97741cae73851b402bb

data/AGENTS.md

@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+## Writing Convention
+
+Use ASD-STE100 (Simplified Technical English) for all communication:
+
+- Write short sentences (20 words maximum)
+- Use active voice
+- Use approved vocabulary only
+- Use one meaning per word
+- Write instructions as commands
+
+## Coding Conventions
+
+### RDoc Documentation
+
+Add RDoc comments to all public classes and methods. Follow this format:
+
+```ruby
+##
+# Short description of the class or method.
+#
+# @param name [Type] Description of the parameter.
+# @return [Type] Description of the return value.
+# @raise [ErrorClass] Description of when this error occurs.
+#
+# @example
+#   result = method_name(arg)
+#   # => expected output
+```
+
+Apply this requirement to all new code and modified code.
+
+### Git Commits
+
+- Make commits atomic: include only one coherent change or fix
+- Do not mix unrelated work in a single commit
+- Write succinct commit messages that describe the change
+- Add both co-authors to each commit message:
+  ```
+  Co-Authored-By: Leandro Marcucci <leanucci@gmail.com>
+  Co-Authored-By: Claude <noreply@anthropic.com>
+  ```
+
+## Project Overview
+
+wsaa-ruby is a Ruby gem for authenticating with AFIP's WSAA (Web Service de Autenticación y Autorización). It handles the login process to obtain TOKEN and SIGN credentials needed to call other AFIP services like WSFE (electronic invoicing).
+
+## Build & Test Commands
+
+```bash
+bundle install          # Install dependencies
+bundle exec rspec       # Run all RSpec tests
+bundle exec rake        # Run default task (specs)
+```
+
+Run a single test file:
+```bash
+bundle exec rspec spec/wsaa/client_spec.rb
+```
+
+## Required Environment
+
+- Ruby >= 2.7.0 (see gemspec)
+- Valid AFIP X.509 certificate and private key
+- Certificate must be registered with AFIP for the target service
+
+## Architecture
+
+### Core Classes
+
+- **`Wsaa`** (`lib/wsaa.rb`) - Main module with configuration and authentication entry points
+- **`Wsaa::Client`** (`lib/wsaa/client.rb`) - Orchestrates the authentication flow
+- **`Wsaa::Tra`** (`lib/wsaa/tra.rb`) - Builds the Ticket de Requerimiento de Acceso XML
+- **`Wsaa::CmsSigner`** (`lib/wsaa/cms_signer.rb`) - Signs TRA using OpenSSL PKCS#7
+- **`Wsaa::Credentials`** (`lib/wsaa/credentials.rb`) - Immutable value object for TOKEN/SIGN
+- **`Wsaa::CredentialStore`** (`lib/wsaa/credential_store.rb`) - File-based credential caching
+- **`Wsaa::Configuration`** (`lib/wsaa/configuration.rb`) - Configuration with validation
+- **`Wsaa::Errors`** (`lib/wsaa/errors.rb`) - Custom exceptions
+
+### Authentication Flow
+
+1. `Wsaa.authenticate` checks for cached credentials in `CredentialStore`
+2. If no valid cache, builds TRA XML with service name and time boundaries
+3. Signs TRA using CMS/PKCS#7 with certificate and private key
+4. Calls WSAA `loginCms` SOAP operation via Savon
+5. Parses response to extract TOKEN and SIGN
+6. Caches credentials for reuse until expiration
+
+### SOAP Communication
+
+Uses Savon ~> 2.0 for AFIP web services:
+- **Testing (Homologación)**: `https://wsaahomo.afip.gov.ar/ws/services/LoginCms`
+- **Production**: `https://wsaa.afip.gov.ar/ws/services/LoginCms`
+
+## Usage Example
+
+```ruby
+require 'wsaa'
+
+Wsaa.configure do |config|
+  config.pkey = 'path/to/private_key'
+  config.cert = 'path/to/certificate'
+  config.service = 'wsfe'
+  config.environment = :testing  # or :production
+end
+
+credentials = Wsaa.authenticate
+credentials.token  # => "PD94bWwg..."
+credentials.sign   # => "GGG2XMe..."
+```
+
+## Key Dependencies
+
+- **savon** (~> 2.0) - SOAP client
+- **rack** (~> 2.0) - Pinned for httpi compatibility
+- **openssl** - Ruby stdlib, for PKCS#7 signing
+- **rexml** - Ruby stdlib, for XML building
+
+## Documentation
+
+- [WSAA Technical Specification (PDF)](https://www.afip.gov.ar/ws/WSAA/Especificacion_Tecnica_WSAA_1.2.0.pdf)

data/CHANGELOG.md

@@ -7,5 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-18
+
 ### Added
-- Initial gem structure
+- RDoc documentation for all public classes and methods
+- GitHub Actions CI workflow for running tests on PRs
+- GitHub Actions release workflow for publishing to RubyGems
+
+## [0.1.0] - 2026-08-18
+
+### Added
+- Initial gem structure (2026-07-30)
+- WSAA authentication client with SOAP support
+- TRA (Ticket de Requerimiento de Acceso) XML builder
+- CMS/PKCS#7 signing with OpenSSL
+- Credentials caching with file-based storage
+- Configuration with testing and production endpoints
+- RSpec test suite with 81 examples
+- Agent configuration files (CLAUDE.md, AGENTS.md)
+
+### Published
+- Released to RubyGems.org as wsaa-ruby 0.1.0

data/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

data/lib/wsaa/client.rb

@@ -2,13 +2,29 @@ require 'savon'
 require 'rexml/document'
 
 module Wsaa
+  ##
+  # WSAA authentication client.
+  #
+  # Orchestrates the authentication flow: builds TRA, signs it, calls WSAA, and caches credentials.
+  #
+  # @attr_reader configuration [Configuration] The client configuration.
   class Client
     attr_reader :configuration
 
+    ##
+    # Creates a new Client.
+    #
+    # @param configuration [Configuration] The client configuration.
     def initialize(configuration)
       @configuration = configuration
     end
 
+    ##
+    # Authenticates with WSAA using cached credentials if available.
+    #
+    # @return [Credentials] The authentication credentials.
+    # @raise [ConfigurationError] If the configuration is invalid.
+    # @raise [AuthenticationError] If authentication fails.
     def authenticate
       configuration.validate!
 
@@ -18,6 +34,12 @@ module Wsaa
       authenticate!
     end
 
+    ##
+    # Authenticates with WSAA, ignoring any cached credentials.
+    #
+    # @return [Credentials] The authentication credentials.
+    # @raise [ConfigurationError] If the configuration is invalid.
+    # @raise [AuthenticationError] If authentication fails.
     def authenticate!
       configuration.validate!
 

data/lib/wsaa/cms_signer.rb

@@ -2,14 +2,33 @@ require 'openssl'
 require 'base64'
 
 module Wsaa
+  ##
+  # Signs data using CMS/PKCS#7 format.
+  #
+  # Creates cryptographic signatures compatible with WSAA requirements.
+  #
+  # @attr_reader certificate [OpenSSL::X509::Certificate] The signing certificate.
+  # @attr_reader private_key [OpenSSL::PKey::RSA] The private key for signing.
   class CmsSigner
     attr_reader :certificate, :private_key
 
+    ##
+    # Creates a new CmsSigner.
+    #
+    # @param cert_path [String] Path to the certificate file in PEM format.
+    # @param pkey_path [String] Path to the private key file in PEM format.
+    # @raise [SigningError] If the certificate or key cannot be loaded.
     def initialize(cert_path:, pkey_path:)
       @certificate = load_certificate(cert_path)
       @private_key = load_private_key(pkey_path)
     end
 
+    ##
+    # Signs data and returns the base64-encoded CMS signature.
+    #
+    # @param data [String] The data to sign.
+    # @return [String] Base64-encoded PKCS#7/CMS signature.
+    # @raise [SigningError] If signing fails.
     def sign(data)
       flags = OpenSSL::PKCS7::BINARY | OpenSSL::PKCS7::NOSMIMECAP
       pkcs7 = OpenSSL::PKCS7.sign(certificate, private_key, data, [], flags)

data/lib/wsaa/configuration.rb

@@ -1,4 +1,12 @@
 module Wsaa
+  ##
+  # Holds configuration for the WSAA client.
+  #
+  # @attr_accessor pkey [String] Path to the private key file.
+  # @attr_accessor cert [String] Path to the certificate file.
+  # @attr_accessor service [String] The AFIP service to authenticate for.
+  # @attr_accessor environment [Symbol] The environment (:testing or :production).
+  # @attr_accessor cache_dir [String] Directory for credential caching.
   class Configuration
     ENDPOINTS = {
       testing: 'https://wsaahomo.afip.gov.ar/ws/services/LoginCms',
@@ -7,18 +15,30 @@ module Wsaa
 
     attr_accessor :pkey, :cert, :service, :environment, :cache_dir
 
+    ##
+    # Creates a new Configuration with default values.
     def initialize
       @environment = :testing
       @service = 'wsfe'
       @cache_dir = '/tmp'
     end
 
+    ##
+    # Returns the WSAA endpoint URL for the current environment.
+    #
+    # @return [String] The endpoint URL.
+    # @raise [ConfigurationError] If the environment is invalid.
     def endpoint
       ENDPOINTS.fetch(environment) do
         raise ConfigurationError, "Invalid environment: #{environment}. Must be :testing or :production"
       end
     end
 
+    ##
+    # Validates the configuration.
+    #
+    # @return [true] If the configuration is valid.
+    # @raise [ConfigurationError] If required values are missing or files do not exist.
     def validate!
       raise ConfigurationError, "Private key path not configured" if pkey.nil? || pkey.empty?
       raise ConfigurationError, "Certificate path not configured" if cert.nil? || cert.empty?

data/lib/wsaa/credential_store.rb

@@ -2,14 +2,30 @@ require 'yaml'
 require 'time'
 
 module Wsaa
+  ##
+  # File-based cache for WSAA credentials.
+  #
+  # Stores credentials as YAML files with date-based filenames.
+  #
+  # @attr_reader cache_dir [String] Directory where cache files are stored.
+  # @attr_reader service [String] The service name used in the cache filename.
   class CredentialStore
     attr_reader :cache_dir, :service
 
+    ##
+    # Creates a new CredentialStore.
+    #
+    # @param cache_dir [String] Directory for cache files.
+    # @param service [String] The service name.
     def initialize(cache_dir:, service:)
       @cache_dir = cache_dir
       @service = service
     end
 
+    ##
+    # Reads cached credentials.
+    #
+    # @return [Credentials, nil] The cached credentials, or nil if not found or expired.
     def read
       return nil unless File.exist?(cache_file_path)
 
@@ -27,15 +43,26 @@ module Wsaa
       nil
     end
 
+    ##
+    # Writes credentials to the cache.
+    #
+    # @param credentials [Credentials] The credentials to cache.
+    # @return [Credentials] The same credentials object.
     def write(credentials)
       File.write(cache_file_path, YAML.dump(credentials.to_h.transform_keys(&:to_s)))
       credentials
     end
 
+    ##
+    # Deletes the cache file.
     def clear
       File.delete(cache_file_path) if File.exist?(cache_file_path)
     end
 
+    ##
+    # Returns the full path to the cache file.
+    #
+    # @return [String] The cache file path.
     def cache_file_path
       File.join(cache_dir, cache_filename)
     end

data/lib/wsaa/credentials.rb

@@ -1,7 +1,21 @@
 module Wsaa
+  ##
+  # Immutable value object for WSAA authentication credentials.
+  #
+  # Holds the TOKEN and SIGN values returned by WSAA after successful authentication.
+  #
+  # @attr_reader token [String] The authentication token.
+  # @attr_reader sign [String] The authentication signature.
+  # @attr_reader expiration_time [Time] When the credentials expire.
   class Credentials
     attr_reader :token, :sign, :expiration_time
 
+    ##
+    # Creates new Credentials.
+    #
+    # @param token [String] The authentication token from WSAA.
+    # @param sign [String] The authentication signature from WSAA.
+    # @param expiration_time [Time] When the credentials expire.
     def initialize(token:, sign:, expiration_time:)
       @token = token.freeze
       @sign = sign.freeze
@@ -9,14 +23,26 @@ module Wsaa
       freeze
     end
 
+    ##
+    # Checks if the credentials have expired.
+    #
+    # @return [Boolean] True if expired.
     def expired?
       Time.now > expiration_time
     end
 
+    ##
+    # Checks if the credentials are valid.
+    #
+    # @return [Boolean] True if not expired and has token and sign.
     def valid?
       !expired? && !token.nil? && !sign.nil?
     end
 
+    ##
+    # Converts credentials to a hash.
+    #
+    # @return [Hash] Hash with :token, :sign, and :expiration_time keys.
     def to_h
       {
         token: token,

data/lib/wsaa/errors.rb

@@ -1,13 +1,30 @@
 module Wsaa
+  ##
+  # Base error class for all WSAA errors.
   class Error < StandardError; end
 
+  ##
+  # Raised when the configuration is invalid or incomplete.
   class ConfigurationError < Error; end
 
+  ##
+  # Raised when CMS/PKCS#7 signing fails.
   class SigningError < Error; end
 
+  ##
+  # Raised when WSAA authentication fails.
+  #
+  # @attr_reader fault_code [String, nil] The SOAP fault code from WSAA.
+  # @attr_reader fault_string [String, nil] The SOAP fault message from WSAA.
   class AuthenticationError < Error
     attr_reader :fault_code, :fault_string
 
+    ##
+    # Creates a new AuthenticationError.
+    #
+    # @param message [String] The error message.
+    # @param fault_code [String, nil] The SOAP fault code.
+    # @param fault_string [String, nil] The SOAP fault message.
     def initialize(message, fault_code: nil, fault_string: nil)
       @fault_code = fault_code
       @fault_string = fault_string

data/lib/wsaa/tra.rb

@@ -1,11 +1,27 @@
 require 'rexml/document'
 
 module Wsaa
+  ##
+  # Builds the Ticket de Requerimiento de Acceso (TRA) XML document.
+  #
+  # The TRA is the access request ticket required by WSAA for authentication.
+  #
+  # @attr_reader service [String] The AFIP service name.
+  # @attr_reader generation_time [Time] When the TRA was generated.
+  # @attr_reader expiration_time [Time] When the TRA expires.
+  # @attr_reader unique_id [Integer] Unique identifier for the request.
   class Tra
     TIMEZONE_OFFSET = '-03:00'
 
     attr_reader :service, :generation_time, :expiration_time, :unique_id
 
+    ##
+    # Creates a new TRA.
+    #
+    # @param service [String] The AFIP service to authenticate for.
+    # @param generation_time [Time, nil] Start of validity period. Defaults to today 00:00:00.
+    # @param expiration_time [Time, nil] End of validity period. Defaults to today 23:59:59.
+    # @param unique_id [Integer, nil] Unique request identifier. Defaults to current timestamp.
     def initialize(service:, generation_time: nil, expiration_time: nil, unique_id: nil)
       @service = service
       @unique_id = unique_id || Time.now.to_i
@@ -13,6 +29,10 @@ module Wsaa
       @expiration_time = expiration_time || default_expiration_time
     end
 
+    ##
+    # Converts the TRA to an XML string.
+    #
+    # @return [String] The TRA as XML.
     def to_xml
       doc = REXML::Document.new
       doc << REXML::XMLDecl.new('1.0', 'UTF-8')

data/lib/wsaa/version.rb

@@ -1,3 +1,5 @@
 module Wsaa
-  VERSION = '0.1.0'
+  ##
+  # Current version of the wsaa-ruby gem.
+  VERSION = '0.2.0'
 end

data/lib/wsaa.rb

@@ -7,24 +7,68 @@ require_relative 'wsaa/credentials'
 require_relative 'wsaa/credential_store'
 require_relative 'wsaa/client'
 
+##
+# Main module for WSAA authentication.
+#
+# Provides a simple interface to authenticate with AFIP's WSAA service.
+#
+# @example Configure and authenticate
+#   Wsaa.configure do |config|
+#     config.pkey = 'path/to/private_key'
+#     config.cert = 'path/to/certificate'
+#     config.service = 'wsfe'
+#     config.environment = :testing
+#   end
+#
+#   credentials = Wsaa.authenticate
+#   credentials.token  # => "PD94bWwg..."
+#   credentials.sign   # => "GGG2XMe..."
 module Wsaa
   class << self
+    ##
+    # Configures the WSAA client.
+    #
+    # @yield [Configuration] The configuration object.
+    #
+    # @example
+    #   Wsaa.configure do |config|
+    #     config.pkey = 'path/to/key'
+    #     config.cert = 'path/to/cert'
+    #   end
     def configure
       yield(configuration)
     end
 
+    ##
+    # Returns the current configuration.
+    #
+    # @return [Configuration] The configuration object.
     def configuration
       @configuration ||= Configuration.new
     end
 
+    ##
+    # Authenticates with WSAA using cached credentials if available.
+    #
+    # @return [Credentials] The authentication credentials.
+    # @raise [ConfigurationError] If the configuration is invalid.
+    # @raise [AuthenticationError] If authentication fails.
     def authenticate
       client.authenticate
     end
 
+    ##
+    # Authenticates with WSAA, ignoring any cached credentials.
+    #
+    # @return [Credentials] The authentication credentials.
+    # @raise [ConfigurationError] If the configuration is invalid.
+    # @raise [AuthenticationError] If authentication fails.
     def authenticate!
       client.authenticate!
     end
 
+    ##
+    # Resets the configuration and client state.
     def reset!
       @configuration = nil
       @client = nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wsaa-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Leandro Marcucci
@@ -66,6 +66,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  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'
 description: Ruby implementation of AFIP WSAA (Web Service de Autenticación y Autorización)
   for authenticating with Argentine tax authority web services
 email:
@@ -74,7 +102,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - LICENSE
 - README.md
@@ -110,7 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Ruby client for AFIP WSAA authentication service