{"id":30772148,"url":"https://github.com/stytchauth/samlshield","last_synced_at":"2025-09-05T00:51:38.707Z","repository":{"id":309241027,"uuid":"1001630408","full_name":"stytchauth/samlshield","owner":"stytchauth","description":"SAML Shield is an open-source Node.js library that proactively validates and rejects malicious SAML assertions at the protocol level, providing drop-in protection against common SAML vulnerabilities without relying on upstream library patches.","archived":false,"fork":false,"pushed_at":"2025-08-05T16:47:43.000Z","size":214,"stargazers_count":53,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-08-29T19:38:09.154Z","etag":null,"topics":["identity","saml","saml2","security"],"latest_commit_sha":null,"homepage":"https://samlshield.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stytchauth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-13T18:03:43.000Z","updated_at":"2025-08-20T12:31:31.000Z","dependencies_parsed_at":"2025-08-10T19:38:31.041Z","dependency_job_id":"12a15589-eb08-4ef7-be12-721b68b49e7e","html_url":"https://github.com/stytchauth/samlshield","commit_stats":null,"previous_names":["stytchauth/samlshield"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/stytchauth/samlshield","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stytchauth%2Fsamlshield","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stytchauth%2Fsamlshield/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stytchauth%2Fsamlshield/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stytchauth%2Fsamlshield/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stytchauth","download_url":"https://codeload.github.com/stytchauth/samlshield/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stytchauth%2Fsamlshield/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273695202,"owners_count":25151482,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["identity","saml","saml2","security"],"created_at":"2025-09-05T00:51:36.639Z","updated_at":"2025-09-05T00:51:38.686Z","avatar_url":"https://github.com/stytchauth.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# samlshield\n\nA Node.js library for validating SAML responses. This library provides security-first SAML validation to protect against common vulnerabilities.\n\n[![Website](https://img.shields.io/badge/Website-samlshield.com-blue)](https://samlshield.com?utm_source=github\u0026utm_medium=referral\u0026utm_campaign=samlshield\u0026utm_content=button)\n![NPM Version](https://img.shields.io/npm/v/%40stytch%2Fsamlshield)\n![GitHub License](https://img.shields.io/github/license/stytchauth/samlshield)\n\n## Features\n\n- **XML External Entity (XXE) Attack Protection**: Prevents malicious external entity references\n- **XML Comment Injection Detection**: Identifies and blocks responses with embedded XML comments\n- **Multiple SignedInfo Element Detection**: Catches signature manipulation attempts\n- **Processing Instruction Validation**: Detects potentially malicious processing instructions\n- **Signature Validation**: Ensures either the response or assertion is properly signed\n- **Structural Validation**: Verifies proper SAML response structure\n\n## Installation\n\nThis library supports npm and yarn package managers:\n\n```bash\n# Using npm\nnpm install @stytch/samlshield\n\n# Using yarn\nyarn add @stytch/samlshield\n```\n\n## Development Setup\n\nFor contributing to this project:\n\n```bash\nyarn install\nyarn hooks # registers Git hooks locally\n```\n\n## Quick Start\n\n```javascript\nimport {\n  validateSAMLResponse,\n  safeValidateSAMLResponse,\n} from \"@stytch/samlshield\";\n\n// Basic usage - throws errors on validation failure\ntry {\n  await validateSAMLResponse({\n    response_xml: \"base64-encoded-saml-response\",\n  });\n  console.log(\"SAML response is valid!\");\n} catch (error) {\n  console.error(\"SAML validation failed:\", error.message);\n}\n\n// Safe usage - returns result object instead of throwing\nconst result = await safeValidateSAMLResponse({\n  response_xml: \"base64-encoded-saml-response\",\n});\n\nif (result.valid) {\n  console.log(\"SAML response is valid!\");\n} else {\n  console.error(\"Validation errors:\", result.errors);\n}\n```\n\n## Managed Version\n\nFor those who prefer not to manage dependencies and updates, [samlshield.com](https://samlshield.com?utm_source=github\u0026utm_medium=referral\u0026utm_campaign=samlshield\u0026utm_content=button) offers a managed version of this validation service. The managed version provides the same security-first SAML validation without requiring you to maintain or update the library yourself. Check out the [Getting Start here](https://samlshield.com/docs/about-saml-shield?utm_source=github\u0026utm_medium=referral\u0026utm_campaign=samlshield\u0026utm_content=button).\n\n## API Reference\n\n### `validateSAMLResponse(options: ValidateArgs): Promise\u003cvoid\u003e`\n\nMain validation function that validates a SAML response for security vulnerabilities.\n\n**Parameters:**\n\n- `options.response_xml` (string): Base64-encoded SAML response XML\n\n**Throws:**\n\n- `ValidationError`: For basic input validation failures\n- `XMLValidationError`: For XML parsing and structure issues\n- `SAMLExpectedAtLeastOneSignatureError`: When neither response nor assertion is signed\n- `SAMLResponseFailureError`: When the SAML response indicates authentication failure\n\n### `safeValidateSAMLResponse(options: ValidateArgs): Promise\u003cValidateResult\u003e`\n\nWrapper around `validateSAMLResponse` that returns a result object instead of throwing.\n\n**Returns:**\n\n```typescript\n{\n  valid: boolean;\n  errors?: string[];\n}\n```\n\n### Error Classes\n\nAll error classes extend `SAMLShieldError` with additional context:\n\n- `ValidationError`: Basic input validation failures\n- `XMLValidationError`: XML parsing and structure issues\n- `SAMLExpectedAtLeastOneSignatureError`: Missing required signatures\n- `XMLExternalEntitiesForbiddenError`: External entity reference attempts\n- `SAMLResponseFailureError`: SAML authentication failures\n\n## Security Features\n\nThis library implements multiple layers of security validation:\n\n### 1. XML External Entity (XXE) Protection\n\nPrevents attackers from including external entities that could expose sensitive files or cause denial of service.\n\n### 2. XML Comment Injection Prevention\n\nBlocks SAML responses containing XML comments, which can be used to bypass signature validation (CVE-2017-11428 family).\n\n### 3. Multiple SignedInfo Detection\n\nIdentifies responses with multiple SignedInfo elements within a single signature, which can be used for signature wrapping attacks.\n\n### 4. Processing Instruction Validation\n\nAlways detects and blocks processing instructions that could be used for XML canonicalization attacks.\n\n### 5. Signature Requirements\n\nEnsures that either the SAML response or the assertion within it is digitally signed.\n\n## Low-Level XML Utilities\n\nThe library also exports low-level XML utilities for advanced use cases:\n\n```javascript\nimport {\n  createSelector,\n  xmlStringToDOM,\n  xmlBase64ToDOM,\n} from \"@stytch/samlshield\";\n\n// Parse XML from string\nconst dom = xmlStringToDOM(\"\u003csaml:Response\u003e...\u003c/saml:Response\u003e\");\n\n// Parse XML from base64\nconst dom2 = xmlBase64ToDOM(\"base64-encoded-xml\");\n\n// Create XPath selector with SAML namespaces\nconst selector = createSelector(dom);\nconst elements = selector.selectElements(\"//saml2p:Response\");\n```\n\n## Testing\n\nSAML Shield includes comprehensive test coverage:\n\n```bash\n# Run all tests\nyarn test\n```\n\nThe library uses a **contract testing pattern**, providing systematic testing of:\n\n- Valid SAML responses from major identity providers\n- Security vulnerability detection (XXE, comment injection, etc.)\n- Edge cases and error conditions\n\nSee [CONTRACT_TESTING.md](CONTRACT_TESTING.md) for details on the testing approach.\n\n## Development Workflow\n\n### Preparing to push\n\n- `yarn format` - formats TypeScript code\n- `yarn lint` - runs linter\n- `yarn build` - builds and checks types\n- `yarn test` - runs test suite\n\nWe use [`husky`](https://github.com/typicode/husky) to run these all in a pre-commit hook.\n\n## Based on Stytch's Auth API\n\nThis library is based on the battle-tested SAML validation logic from [Stytch's](https://stytch.com) production Auth API service, which processes millions of SAML authentications. The original implementation has been adapted for standalone use while maintaining the same security-first approach.\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstytchauth%2Fsamlshield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstytchauth%2Fsamlshield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstytchauth%2Fsamlshield/lists"}