samlesa 3.4.2 → 3.5.0

package/README.md

@@ -1,44 +1,279 @@
-# samlify · [![构建状态](https://img.shields.io/circleci/build/github/tngan/samlify?style=for-the-badge&logo=circleci)](https://app.circleci.com/pipelines/github/tngan/samlify) [![npm 版本](https://img.shields.io/npm/v/samlify.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/samlify) [![下载量](https://img.shields.io/npm/dm/samlify.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/samlify) [![覆盖率](https://img.shields.io/coveralls/tngan/samlify/master.svg?style=for-the-badge&logo=coveralls)](https://coveralls.io/github/tngan/samlify?branch=master)
+# samlify · [![Build Status](https://img.shields.io/circleci/build/github/tngan/samlify?style=for-the-badge&logo=circleci)](https://app.circleci.com/pipelines/github/tngan/samlify) [![npm version](https://img.shields.io/npm/v/samlify.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/samlify) [![Downloads](https://img.shields.io/npm/dm/samlify.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/samlify) [![Coverage Status](https://img.shields.io/coveralls/tngan/samlify/master.svg?style=for-the-badge&logo=coveralls)](https://coveralls.io/github/tngan/samlify?branch=master)
+
+> **High-level API for Single Sign On (SAML 2.0) based on samlify**
 
 ---
-[English Version](#README.md) | [中文版本](#readmeCN.md)
-## 🔄 This repository is an improved fork of [samlify](https://github.com/tngan/samlify) by [tngan](https://github.com/tngan)
+
+[English Version](#readmemd) | [中文版本](#readmecnm)
+
+## 🔄 This Repository
+
+This is an improved fork of [samlify](https://github.com/tngan/samlify) by [tngan](https://github.com/tngan).
 
 ### Key Improvements
 
-- 📦 Converted from CJS to ESModule
-- ✅ Replaced `@authenio/xml-encryption` with `xml-encryption` and added support for sha256/512 encryption key OAEP digest methods
-- ✅ Upgraded `@xmldom/xmldom` to the latest version
-- 🛠️ Fixed encrypted assertion signature verification by adding `EncryptedAssertion` field extraction logic
-- 📦 Added default `AttributeConsumingService` element generation for ServiceProvider
-- 📦 Added partial Artifact binding support
-- 🗑️ Removed custom template support for IdentityProvider and improved parameter passing
-- 🔒 Upgraded default signature algorithm to SHA-256 and default encryption to AES_256_GCM
-- 🧪 Added built-in XML XSD validator
-- 🐛 Improved handling of HTTP-Redirect binding without DEFLATE compression
-- 🔓 Automatic detection of encrypted assertions without explicit flags
-- 📝 Added AttributeConsumingService to default elementsOrder
-- ✅ Tested against Burp SAML Raider (XSW and XXE attacks)
-- ⚡ Migrated tests to Vitest
+- 📦 **ESModule Support**: Converted from CommonJS to ESModule
+- ✅ **Enhanced Encryption**: Replaced `@authenio/xml-encryption` with `xml-encryption`, added support for SHA-256/512 encryption key OAEP digest methods
+- ✅ **Updated Dependencies**: Upgraded `@xmldom/xmldom` to the latest version
+- 🛠️ **Fixed Encrypted Assertion**: Improved encrypted assertion signature verification with `EncryptedAssertion` field extraction
+- 📦 **Default AttributeConsumingService**: Added default `AttributeConsumingService` element generation for ServiceProvider
+- 📦 **Artifact Binding**: Added partial Artifact binding support
+- 🔒 **Security Upgrades**: Default signature algorithm upgraded to SHA-256, default encryption to AES_256_GCM
+- 🧪 **XML Validation**: Built-in XML XSD validator
+- 🐛 **Bug Fixes**: Improved HTTP-Redirect binding handling without DEFLATE compression
+- 🔓 **Auto Detection**: Automatic detection of encrypted assertions without explicit flags
+- ✅ **Security Tested**: Tested against Burp SAML Raider (XSW and XXE attacks)
+- ⚡ **Faster Testing**: Migrated tests to Vitest
 
 ---
 
-## Welcome PRs
+## 📖 Documentation
+
+Full documentation is available at [https://samlify.js.org](https://samlify.js.org).
 
-Contributions are welcome! Please feel free to submit pull requests or provide integration examples with other frameworks.
+### Quick Links
+
+- [Getting Started](docs/guide.md)
+- [Service Provider Configuration](docs/sp-configuration.md)
+- [Identity Provider Configuration](docs/idp-configuration.md)
+- [Supported Algorithms](#supported-algorithms)
+- [Examples](docs/examples.md)
 
 ---
 
-## How to use?
+## 🚀 Installation
+
+```bash
+npm install samlesa
+```
+
+---
+
+## 📦 Supported Algorithms
+
+### Signature Algorithms
+
+| Algorithm | URI | Security Level | Recommendation |
+|-----------|-----|----------------|----------------|
+| **RSA-SHA256** | `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256` | ✅ High | ⭐ **Recommended** |
+| RSA-SHA384 | `http://www.w3.org/2001/04/xmldsig-more#rsa-sha384` | ✅ High | ✅ Supported |
+| RSA-SHA512 | `http://www.w3.org/2001/04/xmldsig-more#rsa-sha512` | ✅ High | ✅ Supported |
+| RSA-PSS-SHA256 | `http://www.w3.org/2007/05/xmldsig-more#rsa-pss-sha256` | ✅✅ Very High | ✅ Supported |
+| ECDSA-SHA256 | `http://www.w3.org/2007/05/xmldsig-more#ecdsa-sha256` | ✅ High | ✅ Supported |
+| ECDSA-SHA384 | `http://www.w3.org/2007/05/xmldsig-more#ecdsa-sha384` | ✅ High | ✅ Supported |
+| ECDSA-SHA512 | `http://www.w3.org/2007/05/xmldsig-more#ecdsa-sha512` | ✅ High | ✅ Supported |
+| EdDSA-Ed25519 | `http://www.w3.org/2007/05/xmldsig-more#eddsa-ed25519` | ✅✅ Very High | ✅ Supported |
+| EdDSA-Ed448 | `http://www.w3.org/2021/04/xmldsig-more#eddsa-ed448` | ✅✅ Very High | ✅ Supported |
+| ~~RSA-SHA1~~ | `http://www.w3.org/2000/09/xmldsig#rsa-sha1` | ❌ Low | ⚠️ Deprecated |
+
+### Encryption Algorithms (Data)
+
+| Algorithm | URI | Mode | Recommendation |
+|-----------|-----|------|----------------|
+| **AES-256-GCM** | `http://www.w3.org/2009/xmlenc11#aes256-gcm` | GCM | ⭐ **Recommended** |
+| AES-128-GCM | `http://www.w3.org/2009/xmlenc11#aes128-gcm` | GCM | ✅ Supported |
+| AES-256-CBC | `http://www.w3.org/2001/04/xmlenc#aes256-cbc` | CBC | ✅ Supported |
+| AES-128-CBC | `http://www.w3.org/2001/04/xmlenc#aes128-cbc` | CBC | ✅ Supported |
+| AES-256-CTR | `http://www.w3.org/2009/xmlenc11#aes256-ctr` | CTR | ✅ Supported |
+| ~~TripleDES~~ | `http://www.w3.org/2001/04/xmlenc#tripledes-cbc` | CBC | ⚠️ Legacy Only |
+
+### Key Encryption Algorithms
+
+| Algorithm | URI | Recommendation |
+|-----------|-----|----------------|
+| **RSA-OAEP-MGF1P** | `http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p` | ⭐ **Recommended** |
+| RSA-OAEP | `http://www.w3.org/2009/xmlenc11#rsa-oaep` | ✅ Supported |
+| AES-256-KW | `http://www.w3.org/2001/04/xmlenc#kw-aes256` | ✅ Supported |
+| ~~RSA-1_5~~ | `http://www.w3.org/2001/04/xmlenc#rsa-1_5` | ⚠️ Deprecated |
+
+---
+
+## 🔧 Usage
+
+### As a Service Provider (SP)
+
+```typescript
+import { ServiceProvider, IdentityProvider } from 'samlesa';
+
+// Initialize Service Provider
+const sp = ServiceProvider({
+  metadata: readFileSync('./sp-metadata.xml'),
+  privateKey: readFileSync('./sp-key.pem'),
+  signingCert: readFileSync('./sp-cert.cer'),
+  isAssertionEncrypted: true,
+  wantAssertionsSigned: true,
+  wantMessageSigned: true,
+});
+
+// Initialize Identity Provider
+const idp = IdentityProvider({
+  metadata: readFileSync('./idp-metadata.xml'),
+});
+
+// Create login request
+const { context: samlRequest, entityEndpoint } = sp.createLoginRequest(idp, 'redirect');
+
+// Parse login response
+const { extract } = await sp.parseLoginResponse(idp, 'redirect', {
+  body: { SAMLResponse: responseFromIdp }
+});
+
+console.log('User:', extract.nameID);
+```
+
+### As an Identity Provider (IdP)
+
+```typescript
+import { IdentityProvider, ServiceProvider } from 'samlesa';
+
+// Initialize Identity Provider
+const idp = IdentityProvider({
+  metadata: readFileSync('./idp-metadata.xml'),
+  privateKey: readFileSync('./idp-key.pem'),
+  signingCert: readFileSync('./idp-cert.cer'),
+  isAssertionEncrypted: true,
+  wantAuthnRequestsSigned: true,
+});
+
+// Initialize Service Provider
+const sp = ServiceProvider({
+  metadata: readFileSync('./sp-metadata.xml'),
+});
+
+// Parse login request
+const { extract } = await idp.parseLoginRequest(sp, 'redirect', {
+  query: { SAMLRequest: requestFromSp }
+});
+
+// Create login response
+const { context: samlResponse } = await idp.createLoginResponse({
+  sp,
+  requestInfo: { extract },
+  binding: 'post',
+  user: { NameID: 'user@example.com' },
+});
+```
+
+### Artifact Binding Support
+
+```typescript
+import { ServiceProvider, IdentityProvider } from 'samlesa';
+
+// Create SOAP login request (Artifact binding)
+const soapRequest = await sp.createLoginSoapRequest(idp, 'artifact', {
+  inResponseTo: '_requestId',
+});
+
+// Parse Artifact Resolve request
+const artifactResult = await sp.parseLoginRequestResolve(idp, soapXml);
 
-Refer to the `type/flows.test.ts` test cases and the original documentation at [https://samlify.js.org](https://samlify.js.org). Note that some parameters have been changed in this fork.
+// Resolve SAML Response by Artifact ID
+const responseResult = await sp.parseLoginResponseResolve(idp, artifactId, request);
+```
 
 ---
 
-## Generating Keys
+## 🔐 Security Features
 
-Use OpenSSL to generate keys and certificates for testing. Private keys can be password-protected (optional). Here are the commands:
+- ✅ **XXE Protection**: Built-in XML External Entity attack prevention
+- ✅ **XSW Protection**: Tested against XML Signature Wrapping attacks
+- ✅ **Schema Validation**: XML Schema validation for all SAML messages
+- ✅ **Signature Verification**: Comprehensive signature validation
+- ✅ **Time Validation**: Configurable clock drift tolerance
+- ✅ **Destination Validation**: Endpoint URL verification
+- ✅ **Certificate Validation**: X.509 certificate validation
+
+---
+
+## 📁 Project Structure
+
+```
+samlify/
+├── src/                      # Source code
+│   ├── binding-artifact.ts   # Artifact binding implementation
+│   ├── binding-post.ts       # POST binding implementation
+│   ├── binding-redirect.ts   # Redirect binding implementation
+│   ├── entity-idp.ts         # Identity Provider entity
+│   ├── entity-sp.ts          # Service Provider entity
+│   ├── libsaml.ts            # SAML utilities
+│   └── schemaValidator.ts    # XML Schema validation
+├── test/                     # Test files
+│   ├── artifact.test.ts      # Artifact binding tests
+│   ├── flow.test.ts          # Flow tests
+│   └── key/                  # Test certificates
+├── docs/                     # Documentation
+└── scripts/                  # Utility scripts
+    └── generate-certs.js     # Certificate generation
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run with coverage
+npm run test:coverage
+
+# Run artifact binding tests only
+npm run test:artifact
+
+# Fast test run (parallel)
+npm run test:fast
+```
+
+---
+
+## 🛠️ Development
 
 ```bash
-openssl genrsa -passout pass:foobar -out encryptKey.pem 4096
-openssl req -new -x509 -key encryptKey.pem -out encryptionCert.cer -days 3650
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Fast build (incremental)
+npm run build:fast
+
+# Generate test certificates (requires OpenSSL)
+npm run generate-certs
+```
+
+---
+
+## 📝 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to:
+
+- Submit pull requests
+- Report issues
+- Provide integration examples with other frameworks
+- Improve documentation
+
+---
+
+## 📧 Support
+
+- **Issues**: [GitHub Issues](https://github.com/Veclea/samlify/issues)
+- **Documentation**: [https://samlify.js.org](https://samlify.js.org)
+- **Email**: vemocle@gmail.com
+
+---
+
+## 🔗 Related Links
+
+- [Original samlify](https://github.com/tngan/samlify)
+- [SAML 2.0 Specification](https://www.oasis-open.org/standards#samlv2.0)
+- [SAML Raider (Security Testing)](https://github.com/SAMLRaider/SAMLRaider)