node-firebird 2.3.3 → 2.4.0

package/poc/node_modules/node-firebird/CI_DEBUGGING_GUIDE.md

@@ -1,148 +0,0 @@
-# CI Debugging Guide
-
-## Firebird Log Display on Test Failures
-
-### Overview
-When tests fail in the CI pipeline, the workflow automatically displays Firebird server logs to help with debugging. This feature was added to make it easier to diagnose connection, authentication, and other Firebird-related issues.
-
-### What Gets Displayed
-
-When a test fails, the following information is automatically shown:
-
-1. **Firebird Server Log** (last 100 lines)
-   - Location: `/firebird/log/firebird.log` inside the Docker container
-   - Contains Firebird server events, errors, warnings, and diagnostic information
-   - Useful for diagnosing authentication failures, connection issues, and SQL errors
-
-2. **Docker Container Status**
-   - Shows if the Firebird container is running, stopped, or has exited
-   - Displays container ID, image, status, and ports
-   - Command: `docker ps -a`
-
-3. **Docker Container Logs** (last 50 lines)
-   - Shows the stdout/stderr output from the Firebird container
-   - Includes startup messages and any runtime errors
-   - Command: `docker logs firebird --tail 50`
-
-### How It Works
-
-The workflow uses GitHub Actions' conditional execution:
-
-```yaml
-- name: Show Firebird log on failure
-  if: failure()
-  run: |
-    # Display Firebird log
-    docker exec firebird tail -n 100 /firebird/log/firebird.log || echo "Could not read firebird.log"
-    # Display container status
-    docker ps -a
-    # Display container logs
-    docker logs firebird --tail 50
-```
-
-**Key Features:**
-- Only runs when previous steps fail (`if: failure()`)
-- No performance impact on successful builds
-- Gracefully handles missing log file with fallback message
-- Works with all Firebird versions (3, 4, 5)
-
-### Interpreting the Output
-
-#### Common Firebird Log Patterns
-
-**Authentication Failures:**
-```
-INET/inet_error: read errno = 104
-login by SYSDBA failed (authentication failed)
-```
-
-**Connection Issues:**
-```
-INET/inet_error: connect errno = 111
-connection refused
-```
-
-**Database Errors:**
-```
-Database: /firebird/data/test.fdb
-validation error
-```
-
-#### Docker Container Status
-
-**Running Container:**
-```
-CONTAINER ID   IMAGE                    STATUS
-abc123...      firebirdsql/firebird:5   Up 2 minutes
-```
-
-**Stopped Container:**
-```
-CONTAINER ID   IMAGE                    STATUS
-abc123...      firebirdsql/firebird:5   Exited (1) 2 minutes ago
-```
-
-### Testing Locally
-
-To test the Firebird log display locally:
-
-1. Start Firebird Docker container:
-   ```bash
-   docker run -d --name firebird \
-     -e FIREBIRD_ROOT_PASSWORD="masterkey" \
-     -p 3050:3050 \
-     firebirdsql/firebird:5
-   ```
-
-2. View Firebird log:
-   ```bash
-   docker exec firebird tail -n 100 /firebird/log/firebird.log
-   ```
-
-3. Check container status:
-   ```bash
-   docker ps -a
-   ```
-
-4. View container logs:
-   ```bash
-   docker logs firebird --tail 50
-   ```
-
-### Troubleshooting
-
-**"Could not read firebird.log" message:**
-- The log file may not exist yet (Firebird hasn't started)
-- The log path may be different (though it's standard across versions 3-5)
-- Check the Docker container logs for more information
-
-**No output shown:**
-- Verify the step ran (check GitHub Actions logs)
-- Ensure the `if: failure()` condition was triggered
-- Check that the Firebird container is running
-
-**Container not found:**
-- The container may have been removed before this step ran
-- Check earlier steps in the workflow for container lifecycle issues
-
-### Related Documentation
-
-- [Firebird Documentation](https://firebirdsql.org/en/documentation/)
-- [GitHub Actions Conditional Execution](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idif)
-- [Docker Logging](https://docs.docker.com/config/containers/logging/)
-
-### Contributing
-
-If you encounter issues with the log display or have suggestions for improvement:
-
-1. Check if the Firebird log path has changed in newer versions
-2. Verify the Docker container name matches (`firebird`)
-3. Test with different Firebird versions (3, 4, 5)
-4. Submit an issue or pull request with your findings
-
-### Version History
-
-- **2026-03-23**: Initial implementation
-  - Added automatic Firebird log display on test failure
-  - Includes Docker container status and logs
-  - Works with Firebird 3, 4, and 5

package/poc/node_modules/node-firebird/ENCRYPTION_CALLBACK.md

@@ -1,152 +0,0 @@
-# Database Encryption Key Callback Implementation
-
-This document describes the implementation of Firebird protocol 14 and 15 database encryption key callback support in node-firebird.
-
-## Overview
-
-Firebird 3.0.1 introduced protocol version 14 to fix a bug in database encryption key callback, and version 15 (3.0.2) extended this to support database encryption key callback during the connect phase. This allows connections to encrypted databases that serve as their own security database.
-
-## Implementation Details
-
-### 1. Protocol Support
-
-The implementation adds support for:
-- **Protocol 14**: Database encryption key callback (Firebird 3.0.1+)
-- **Protocol 15**: Database encryption key callback in connect phase (Firebird 3.0.2+)
-
-Both protocols were already defined in the constants but the actual callback mechanism (`op_crypt_key_callback`, opcode 97) was not implemented.
-
-### 2. Connection Option
-
-A new connection option `dbCryptConfig` has been added:
-
-```javascript
-{
-  dbCryptConfig: 'base64:bXlTZWNyZXRLZXk=' // Base64-encoded key
-  // or
-  dbCryptConfig: 'myPlainTextKey'  // Plain text key (UTF-8 encoded)
-  // or
-  dbCryptConfig: undefined  // Empty response (default)
-}
-```
-
-### 3. Message Flow
-
-When connecting to an encrypted database:
-
-1. Client sends `op_connect` with supported protocol versions
-2. Server responds with `op_accept`, `op_cond_accept`, or `op_accept_data`
-3. If database is encrypted, server sends `op_crypt_key_callback` (opcode 97)
-4. Client reads server plugin data (currently unused)
-5. Client responds with encryption key from `dbCryptConfig` option
-6. Server validates the key and continues with connection or returns error
-7. Connection proceeds normally if key is valid
-
-### 4. Code Changes
-
-#### lib/wire/connection.js
-
-- **sendOpCryptKeyCallback()**: New method to send the encryption key callback response
-- **parseDbCryptConfig()**: Helper function to parse base64 or plain text keys
-- **decodeResponse()**: Added case for `Const.op_crypt_key_callback` to handle the callback
-
-#### lib/index.d.ts
-
-- Added `dbCryptConfig?: string` to the `Options` interface
-
-#### Tests
-
-- **test/protocol.js**: Added test for `op_crypt_key_callback` opcode definition
-- **test/db-crypt-config.js**: New test file with 6 tests for option handling and encoding
-
-#### Documentation
-
-- **README.md**: Added documentation and examples for database encryption
-- **Roadmap.md**: Updated to mark database encryption callback as implemented
-
-## Security Considerations
-
-1. **Key Storage**: The encryption key is passed as a connection option. Applications should:
-   - Store keys securely (environment variables, key management systems)
-   - Never hardcode keys in source code
-   - Never commit keys to version control
-
-2. **Wire Encryption**: Database encryption keys can be transmitted unencrypted if:
-   - `wireCrypt` is disabled (`WIRE_CRYPT_DISABLE`)
-   - Legacy authentication is used
-   - Server doesn't support wire encryption
-   
-   **Recommendation**: Always use `wireCrypt: Firebird.WIRE_CRYPT_ENABLE` (default)
-
-3. **Empty Keys**: If `dbCryptConfig` is not provided or is empty, an empty response is sent. Depending on the database encryption plugin, this may:
-   - Work (if the plugin doesn't require a key)
-   - Fail with an error
-   - Silently fail (security risk)
-
-## Testing
-
-All tests pass including:
-- Protocol constant definitions
-- Option parsing and validation
-- Base64 encoding/decoding
-- UTF-8 plain text encoding
-
-## Reference Implementation
-
-This implementation is based on the Jaybird JDBC driver:
-- Issue: https://github.com/FirebirdSQL/jaybird/issues/561
-- Commit: https://github.com/FirebirdSQL/jaybird/commit/df6d50bb07589ef554e6f5fe67c5a561ace979e8
-
-## Limitations
-
-1. **No Plugin System**: Unlike Jaybird's future-ready plugin architecture, this implementation uses a fixed response mechanism. A plugin system could be added in the future.
-
-2. **Protocol 14/15 Only**: Database encryption callback is only available for protocol versions 14 and 15 (Firebird 3.0.1+).
-
-3. **No Native Support**: This implementation is for pure JavaScript client only. Native and embedded connections are not supported.
-
-## Example Usage
-
-### Connecting to an Encrypted Database
-
-```javascript
-const Firebird = require('node-firebird');
-
-// Using base64-encoded key
-Firebird.attach({
-  host: 'localhost',
-  port: 3050,
-  database: '/path/to/encrypted.fdb',
-  user: 'SYSDBA',
-  password: 'masterkey',
-  dbCryptConfig: 'base64:bXlTZWNyZXRLZXkxMjM0NTY=',
-  wireCrypt: Firebird.WIRE_CRYPT_ENABLE // Recommended
-}, function(err, db) {
-  if (err) throw err;
-  
-  console.log('Connected to encrypted database');
-  db.query('SELECT * FROM MY_TABLE', function(err, result) {
-    console.log(result);
-    db.detach();
-  });
-});
-
-// Using plain text key
-Firebird.attach({
-  host: 'localhost',
-  database: '/path/to/encrypted.fdb',
-  user: 'SYSDBA',
-  password: 'masterkey',
-  dbCryptConfig: 'mySecretKey123'
-}, function(err, db) {
-  if (err) throw err;
-  // ...
-});
-```
-
-## Future Enhancements
-
-1. **Plugin Architecture**: Similar to Jaybird, implement a plugin system for more complex encryption callbacks
-2. **Multiple Callbacks**: Handle cases where the server requests multiple callbacks
-3. **Key Derivation**: Support for key derivation functions (PBKDF2, scrypt, etc.)
-4. **Protocol 16/17**: Add support for Firebird 4.0 protocol versions

package/poc/node_modules/node-firebird/FIREBIRD_LOG_FEATURE.md

@@ -1,145 +0,0 @@
-# Firebird Log Display Feature
-
-## Quick Reference
-
-### What Was Added
-Automatic display of Firebird server logs when CI tests fail.
-
-### Where
-- **Implementation**: `.github/workflows/node.js.yml` (lines 77-93)
-- **Documentation**: `CI_DEBUGGING_GUIDE.md`
-
-### When It Runs
-Only when tests fail in CI (uses `if: failure()` condition)
-
-### What It Shows
-1. Last 100 lines of Firebird server log
-2. Docker container status
-3. Last 50 lines of Docker container logs
-
-## Quick Commands
-
-### View logs locally:
-```bash
-# Start Firebird container
-docker run -d --name firebird \
-  -e FIREBIRD_ROOT_PASSWORD="masterkey" \
-  -p 3050:3050 \
-  firebirdsql/firebird:5
-
-# View Firebird log
-docker exec firebird tail -n 100 /firebird/log/firebird.log
-
-# Check container status
-docker ps -a
-
-# View container logs
-docker logs firebird --tail 50
-```
-
-### Test the workflow locally:
-```bash
-# Validate YAML syntax
-python3 -c "import yaml; yaml.safe_load(open('.github/workflows/node.js.yml'))"
-```
-
-## Implementation Details
-
-### GitHub Actions Step
-```yaml
-- name: Show Firebird log on failure
-  if: failure()
-  run: |
-    echo "=========================================="
-    echo "Firebird Server Log (last 100 lines):"
-    echo "=========================================="
-    docker exec firebird tail -n 100 /firebird/log/firebird.log || echo "Could not read firebird.log"
-    echo ""
-    echo "=========================================="
-    echo "Docker container status:"
-    echo "=========================================="
-    docker ps -a
-    echo ""
-    echo "=========================================="
-    echo "Docker container logs:"
-    echo "=========================================="
-    docker logs firebird --tail 50
-```
-
-### Key Features
-- ✅ Conditional execution (only on failure)
-- ✅ Graceful error handling
-- ✅ Formatted output with clear sections
-- ✅ Works with Firebird 3, 4, and 5
-- ✅ Zero performance impact on successful builds
-
-## Common Issues & Solutions
-
-### Issue: "Could not read firebird.log"
-**Solution**: Check Docker container logs, the file might not exist yet
-
-### Issue: Container not found
-**Solution**: Verify container name is "firebird" and it's still running
-
-### Issue: Empty log output
-**Solution**: Firebird might not have written logs yet, check startup time
-
-## Firebird Log Locations
-
-### In Docker Container
-- **Log file**: `/firebird/log/firebird.log`
-- **Config**: `/firebird/etc/firebird.conf`
-- **Install**: `/opt/firebird`
-
-### Consistent Across Versions
-The log path is the same for:
-- Firebird 3.x
-- Firebird 4.x
-- Firebird 5.x
-
-## Maintenance
-
-### If log path changes:
-1. Update `.github/workflows/node.js.yml`
-2. Update `CI_DEBUGGING_GUIDE.md`
-3. Test with all Firebird versions
-
-### If more lines needed:
-- Change `tail -n 100` to desired number
-- Change `--tail 50` for Docker logs
-
-### If additional diagnostics needed:
-Add new echo sections in the workflow step
-
-## Related Files
-
-- `.github/workflows/node.js.yml` - CI workflow with log display
-- `CI_DEBUGGING_GUIDE.md` - Comprehensive debugging guide
-- `README.md` - Main project documentation
-
-## Version History
-
-- **2026-03-23**: Initial implementation
-  - Added conditional log display on test failure
-  - Created comprehensive documentation
-  - Tested with Firebird 3, 4, 5
-
-## Contributing
-
-To improve this feature:
-1. Test with different Firebird versions
-2. Verify log paths remain consistent
-3. Submit issues or PRs with enhancements
-4. Update documentation as needed
-
-## Support
-
-For questions or issues:
-1. Check `CI_DEBUGGING_GUIDE.md` for troubleshooting
-2. Review GitHub Actions logs for the step execution
-3. Test locally using provided commands
-4. Submit an issue if problems persist
-
----
-
-**Note**: This feature is designed for CI environments. For local development, use the Docker commands directly.