@smartledger/elliptic-fix/README.md

Security fix for signature malleability vulnerability in Elliptic package v6.5.5 used by bsv@1.5.6

# BSV Elliptic Fix

Security fix for the signature malleability vulnerability in Elliptic package v6.5.5, specifically in the context of bsv@1.5.6.

## Quick Start

```bash
npm install @smartledger/elliptic-fix
```

Then in your code, replace:
```javascript
const elliptic = require('elliptic');
```

with:
```javascript
const elliptic = require('@smartledger/elliptic-fix');
```

That's it! The fix is automatically applied and verified during installation.

## Vulnerability Details

The vulnerability exists in the EDDSA implementation's `verify` function in Elliptic v6.5.5, which does not validate the signature's S value. This allows signatures to be malleable when S ≥ n (where n is the curve order).

### Impact
- Signatures with S values greater than or equal to the curve order can be considered valid
- This enables signature malleability attacks
- Affects applications using bsv@1.5.6 which depends on elliptic@6.5.5

## Fix Implementation

The fix adds validation in the EDDSA `verify` function to reject signatures where:
- S ≥ n (curve order)
- S < 0 (negative values)

### Technical Details
```javascript
// Added validation check
if (signature.S().gte(this.curve.n) || signature.S().isNeg()) {
    return false;
}
```

## Verification

The package includes automatic verification during installation. You can also manually verify:

```javascript
const elliptic = require('@smartledger/elliptic-fix');
const ed = new elliptic.eddsa('ed25519');

// Your existing code using elliptic...
// All valid signatures will work normally
// Malleable signatures (S >= n) will be rejected
```

## Compatibility

- Works with bsv@1.5.6
- Maintains all existing elliptic functionality
- Only patches the EDDSA signature verification
- Zero impact on valid signatures

## Security

This fix:
- Prevents signature malleability attacks
- Maintains compatibility with valid signatures
- Is automatically verified during installation
- Uses the same validation as the official fix in elliptic@6.5.7+

## Alternative Solutions

If you prefer not to use this package, you can:
1. Upgrade to bsv versions that use elliptic@6.5.7 or later
2. Use npm overrides to force elliptic@6.5.7:
   ```json
   {
     "overrides": {
       "elliptic": "6.5.7"
     }
   }
   ```

## Testing

To run the test suite:
```bash
npm test
```

## Contributing

Issues and pull requests are welcome! Please submit them to our [GitHub repository](https://github.com/smartledger/elliptic-fix).

## License

MIT

## References

- [Elliptic Package](https://www.npmjs.com/package/elliptic)
- [BSV Package](https://www.npmjs.com/package/bsv)
- [EdDSA Specification](https://tools.ietf.org/html/rfc8032)