校验与低层模块

这一页讲什么

如果高层实体 API 解决不了你的问题，这一页就是继续往下走的入口。这里集中介绍当前实现里最重要的低层能力：

• validate()
• validateMetadata()
• setSchemaValidator()
• setDOMParserOptions()
• Extractor
• SamlLib
• Utility
• Soap

validate(xml, isSoap?)

公开导出：

import { validate } from 'samlesa';

用途：

• 校验普通 SAML 消息的 schema
• 校验 SOAP Artifact 消息的 schema
• 在 SOAP 模式下额外拒绝多个 resolved message

示例：

await validate(xml);
await validate(soapXml, true);

什么时候直接调用它

• 你想在业务入口先挡掉明显非法的 XML
• 你在联调时想先判断问题是不是 schema 层
• 你需要单独验证 Artifact SOAP 包

validateMetadata(xml, isParse?)

公开导出：

import { validateMetadata } from 'samlesa';

用途：

• 校验 metadata 是否符合 XSD
• 可选地识别 metadata 类型

const result = await validateMetadata(xml, true);

console.log(result.metadataType); // 'IdP' | 'SP' | 'both' | 'unknown'

自定义 schema validator

import { setSchemaValidator } from 'samlesa';

setSchemaValidator({
  validate: async (xml, isSoap) => {
    return true;
  }
});

这会替换全局上下文里的 validator。适用场景：

• 测试
• 二次封装
• 接入你自己的校验管线

不建议在普通业务代码里频繁切换。

自定义 DOM parser 选项

import { setDOMParserOptions } from 'samlesa';

setDOMParserOptions({
  locator: true
});

当前默认已经使用静默严格的 DOM parser，所以大多数项目并不需要覆盖它。只有当你明确需要改 parser 选项时，再使用这个入口。

Extractor

公开导出：

import { Extractor } from 'samlesa';

它的定位是“低层字段提取”，而不是完整认证决策器。

当前提取器覆盖了这些典型结构：

• LoginRequest
• LoginResponse
• LogoutResponse
• ArtifactResolve
• ArtifactResponse
• Metadata 中的部分结构

适用场景：

• 调试对端发来的字段
• 做业务层映射
• 在不跑完整高层流程时快速取值

SamlLib

公开导出：

import { SamlLib } from 'samlesa';

这是最核心的低层能力集合之一，当前文档建议重点知道这些方法：

• verifySignature()
• constructSAMLSignature()
• verifyMessageSignature()
• encryptAssertion()
• decryptAssertion()
• replaceTagsByValue()
• attributeStatementBuilder()
• getDigestMethod()
• createKeySection()

什么时候直接用 SamlLib

• 你需要自定义消息模板
• 你要单独复用签名或解密能力
• 你在写协议级测试
• 你在做一个基于 samlesa 的封装库

什么时候不要直接用

如果你只是做常规 SP / IdP 登录流程，高层实体 API 会更稳，出错面也更小。

Utility

公开导出：

import { Utility } from 'samlesa';

这部分包含很多实用工具，当前比较值得知道的有：

• base64Encode() / base64Decode()
• inflateString()
• readPrivateKey()
• normalizeCertificates()
• validateCertificate()
• validateRelayState()
• sanitizeLog()

这层更像基础工具箱，适合业务代码、调试代码或二次封装复用。

Soap

公开导出：

import { Soap } from 'samlesa';

当前主要提供：

• sendArtifactResolve()
• sendArtifactResponse()
• createArt()
• parseArt()
• encodeXmlToIso88591()

适合自己接管 Artifact 后信道、调试 SOAP 原文、或实现更定制的 Artifact 存储与投递策略。

一个很实用的分层建议

第一层

先尝试：

• ServiceProvider
• IdentityProvider

第二层

需要更多可控性时，查看：

• validate()
• validateMetadata()
• Extractor
• Soap

第三层

只有在真正要定制协议细节时，再深入：

• SamlLib
• Utility
• 自定义 validator / parser