zai_payment 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3dde823881d82243bdd2f57882c57cfe06ba21d20ab5402b58a876c7c752e8c
-  data.tar.gz: 37ce743767afba2f834354a81102cc445c544151c26601e59a0f82eb6b967a92
+  metadata.gz: a4b63d2fefc49eb419bc1de0db2cb41c3df25794f6efbf2b9a92ca6091112258
+  data.tar.gz: 1ba74f063b3360b79acafe36a25d43c0b92ae09bee3c5d3da2f3ef30bf4fa5ab
 SHA512:
-  metadata.gz: 0b96c6511bc25c2dcbfe44af58957b160c3bd7ac1fb6aa94fb5708ced6a6e2ff6a209f188f664eb6c857ebe4177f5260191eb62aa1e64924adc57d695815ed38
-  data.tar.gz: 6e2410984fe931c17097f145de9a23e7c6048af308c068e7f590efab9991a21c838aed6158bb1be56863fa9e86090f46599eaffec1cf415e2610c46861de06e1
+  metadata.gz: 209ce54d8809117bb3fe6059c50dc1a6be4a7de974a961506936772b3f0480510b28382445ef113f4bf0ef914b314377bb3ddf5613ee942ad691be818e1d3383
+  data.tar.gz: e8efd4e2b0e5d2d42403d389c4218b95735ae4f1dcf60eb3e1e8012d23750bb2a0b8edd5fcc56f13816bc3c3de955de06f477230df5acce534824a15bebbc0ce

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 ## [Released]
 
+## [1.2.0] - 2025-10-22
+### Added
+- **Webhook Security: Signature Verification** 🔒
+  - `create_secret_key(secret_key:)` - Register a secret key with Zai
+  - `verify_signature(payload:, signature_header:, secret_key:, tolerance:)` - Verify webhook authenticity
+  - `generate_signature(payload, secret_key, timestamp)` - Utility for testing
+  - HMAC SHA256 signature verification with Base64 URL-safe encoding
+  - Timestamp validation to prevent replay attacks (configurable tolerance)
+  - Constant-time comparison to prevent timing attacks
+  - Support for multiple signatures (key rotation scenarios)
+
+### Documentation
+- **NEW**: [Authentication Guide](docs/AUTHENTICATION.md) - Comprehensive guide covering:
+  - Short way: `ZaiPayment.token` (one-liner approach)
+  - Long way: `TokenProvider.new(config:).bearer_token` (advanced control)
+  - Token lifecycle and automatic management
+  - Multiple configurations, testing, error handling
+  - Best practices and troubleshooting
+- **NEW**: [Webhook Security Quick Start](docs/WEBHOOK_SECURITY_QUICKSTART.md) - 5-minute setup guide
+- **NEW**: [Webhook Signature Implementation](docs/WEBHOOK_SIGNATURE.md) - Technical details
+- **NEW**: [Documentation Index](docs/README.md) - Central navigation for all docs
+- **Enhanced**: [Webhook Examples](examples/webhooks.md) - Added 400+ lines of examples:
+  - Complete Rails controller implementation
+  - Sinatra example
+  - Rack middleware example
+  - Background job processing pattern
+  - Idempotency pattern
+- **Enhanced**: [Webhook Technical Guide](docs/WEBHOOKS.md) - Added 170+ lines on security
+- **Reorganized**: All documentation moved to `docs/` folder for better organization
+- **Updated**: README.md - Now concise with clear links to detailed documentation
+
+### Testing
+- 56 new test cases for webhook signature verification
+- All tests passing: 95/95 ✓
+- Tests cover valid/invalid signatures, expired timestamps, malformed headers, edge cases
+
+### Security
+- ✅ OWASP compliance for webhook security
+- ✅ RFC 2104 (HMAC) implementation
+- ✅ RFC 4648 (Base64url) encoding
+- ✅ Protection against timing attacks, replay attacks, and MITM attacks
+
+**Full Changelog**: https://github.com/Sentia/zai-payment/compare/v1.1.0...v1.2.0
+
 ## [1.1.0] - 2025-10-22
 ### Added
 - **Webhooks API**: Full CRUD operations for managing Zai webhooks

data/README.md

@@ -44,67 +44,57 @@ ZaiPayment.configure do |c|
 end
 ```
 
-## 🚀 Authentication
+## 🚀 Quick Start
 
-The Zai Payment gem implements OAuth2 Client Credentials flow for secure authentication with the Zai API. The gem intelligently manages your authentication tokens behind the scenes, so you don't have to worry about token expiration or manual refreshes.
+### Authentication
 
-When you request a token, the gem automatically caches it and reuses it for subsequent requests. Since Zai tokens expire after 60 minutes, the gem monitors the token lifetime and seamlessly refreshes it before expiration — ensuring your API calls never fail due to stale credentials.
-
-This automatic token management means you can focus on building your integration while the gem handles all the authentication complexity for you. Simply configure your credentials once, and the gem takes care of the rest.
-
-For more details about Zai's OAuth2 authentication, see the [official documentation](https://developer.hellozai.com/reference/overview#authentication).
+Get an OAuth2 token with automatic caching and refresh:
 
 ```ruby
-client = ZaiPayment::Auth::TokenProvider.new(config: ZaiPayment.config)
-
-client.bearer_token
+# Simple one-liner (recommended)
+token = ZaiPayment.token
+
+# Or with full control (advanced)
+config = ZaiPayment::Config.new
+config.environment = :prelive
+config.client_id = 'your_client_id'
+config.client_secret = 'your_client_secret'
+config.scope = 'your_scope'
+
+token_provider = ZaiPayment::Auth::TokenProvider.new(config: config)
+token = token_provider.bearer_token
 ```
 
-Or, more easily, you can get a token with the convenience one-liner:
-
-
-```ruby
-ZaiPayment.token
-```
+The gem handles OAuth2 Client Credentials flow automatically - tokens are cached and refreshed before expiration.
 
-## 🚀 Usage
+📖 **[Complete Authentication Guide](docs/AUTHENTICATION.md)** - Two approaches, examples, and best practices
 
 ### Webhooks
 
-The gem provides a comprehensive interface for managing Zai webhooks:
+Manage webhook endpoints:
 
 ```ruby
-# List all webhooks
+# List webhooks
 response = ZaiPayment.webhooks.list
 webhooks = response.data
 
-# List with pagination
-response = ZaiPayment.webhooks.list(limit: 20, offset: 10)
-
-# Get a specific webhook
-response = ZaiPayment.webhooks.show('webhook_id')
-webhook = response.data
-
 # Create a webhook
 response = ZaiPayment.webhooks.create(
   url: 'https://example.com/webhooks/zai',
   object_type: 'transactions',
-  enabled: true,
-  description: 'Production webhook for transactions'
-)
-
-# Update a webhook
-response = ZaiPayment.webhooks.update(
-  'webhook_id',
-  enabled: false,
-  description: 'Temporarily disabled'
+  enabled: true
 )
 
-# Delete a webhook
-response = ZaiPayment.webhooks.delete('webhook_id')
+# Secure your webhooks with signature verification
+secret_key = SecureRandom.alphanumeric(32)
+ZaiPayment.webhooks.create_secret_key(secret_key: secret_key)
 ```
 
-For more examples, see [examples/webhooks.md](examples/webhooks.md).
+**📚 Documentation:**
+- 📖 [Webhook Examples & Complete Guide](examples/webhooks.md) - Full CRUD operations and patterns
+- 🔒 [Security Quick Start](docs/WEBHOOK_SECURITY_QUICKSTART.md) - 5-minute webhook security setup
+- 🏗️ [Architecture & Implementation](docs/WEBHOOKS.md) - Detailed technical documentation
+- 🔐 [Signature Verification Details](docs/WEBHOOK_SIGNATURE.md) - Security implementation specs
 
 ### Error Handling
 
@@ -190,8 +180,22 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 Everyone interacting in the ZaiPayment project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/Sentia/zai-payment/blob/main/CODE_OF_CONDUCT.md).
 
-## 🔗 Resources
+## 📚 Documentation
+
+### Getting Started
+- [**Authentication Guide**](docs/AUTHENTICATION.md) - Two approaches to getting tokens, automatic management
+- [**Webhook Examples**](examples/webhooks.md) - Complete webhook usage guide
+- [**Documentation Index**](docs/README.md) - Full documentation navigation
+
+### Technical Guides
+- [Webhook Architecture](docs/WEBHOOKS.md) - Technical implementation details
+- [Architecture Overview](docs/ARCHITECTURE.md) - System architecture and design
+
+### Security
+- [Webhook Security Quick Start](docs/WEBHOOK_SECURITY_QUICKSTART.md) - 5-minute setup guide
+- [Signature Verification](docs/WEBHOOK_SIGNATURE.md) - Implementation details
 
+### External Resources
 - [Zai Developer Portal](https://developer.hellozai.com/)
 - [Zai API Reference](https://developer.hellozai.com/reference)
-- [AssemblyPay Auth Documentation](https://developer.hellozai.com/docs/introduction)
+- [Zai OAuth Documentation](https://developer.hellozai.com/docs/introduction)