EUDI OpenId4VCI 库

❗ 重要提示！ 在继续之前，请务必阅读EUDI钱包参考实现项目描述

概述

这是一个 Swift 库，它支持 OpenId4VCI (草案 14) 协议。特别是，该库侧重于协议中钱包的角色，用于：

解析凭据颁发者元数据
解析保护颁发服务的授权服务器的元数据
解析由颁发者服务提供的凭据请求
协商凭据颁发请求的授权
提交凭据颁发请求

免责声明

发布的软件是初始开发版本

初始开发版本是一个早期尝试，反映了短时间盒周期内的努力，绝不能被视为最终产品。
初始开发版本可能会随着时间的推移而发生重大变化，可能会引入新功能，但也可能更改或删除现有功能，从而可能破坏与现有代码的兼容性。
初始开发版本在功能范围上受到限制。
初始开发版本可能包含错误或设计缺陷以及其他可能导致系统或其他故障和数据丢失的问题。
与未来版本相比，初始开发版本降低了安全性、隐私性、可用性和可靠性标准。这可能会使软件比成熟软件更慢、更不可靠或更容易受到攻击。
初始开发版本尚未得到全面记录。
软件用户必须执行足够的工程和额外测试，以便正确评估他们的应用程序并确定任何开源组件是否适合在该应用程序中使用。
我们强烈建议不要将此版本的软件投入生产使用。
仅支持该软件的最新版本

如何使用

该库提供了以下主要 API 元素，以方便该 API 的使用者进行与可验证凭据颁发相关的操作：

元数据解析器：与凭据颁发者及其授权服务器交互以获取和解析其元数据的组件。
凭据请求解析器：一个与凭据颁发者交互以解析和验证由颁发者提供的凭据请求的组件。
颁发者组件：一个提供授权和提交凭据颁发请求所需的所有操作的组件。

解析凭据颁发者和授权服务器元数据

要获取凭据颁发者元数据，请使用 CredentialIssuerMetadataResolver Actor，方法如下：

import OpenID4VCI

let credentialIdentifier = try CredentialIdentifier(value: "https://....")
let credentialIssuerIdentifier = try CredentialIssuerId(CREDENTIAL_ISSUER_PUBLIC_URL)
    
let resolver = CredentialIssuerMetadataResolver()
let metadata = await resolver.resolve(
    source: .credentialIssuer(
        credentialIssuerIdentifier
    )
)

switch metadata {
    ...
}

如果失败，原因将在 Error 中返回。

要获取授权服务器的元数据，请使用 AuthorizationServerMetadataResolver，方法如下：

import OpenID4VCI

let resolver = AuthorizationServerMetadataResolver()
let authServerMetadata = await resolver.resolve(url: "https://....")

该 URL 可以从上面的凭据颁发者元数据中获得。

解析凭据请求

CredentialOfferRequestResolver 在内部使用上面提到的两个元数据解析器来解析颁发者及其授权服务器的元数据。

给定一个凭据请求 URL，使用 CredentialOfferRequestResolver 按以下方式对其进行验证并解析为 CredentialOffer：

import OpenID4VCI

let resolver = CredentialOfferRequestResolver()
let result = await resolver
  .resolve(
    source: try .init(
      urlString: url
    )
  )
    
switch result {
    ...
}

凭据颁发

OpenID4VCI 规范定义了两种颁发流程：

授权码流程（钱包发起的流程）
预授权码流程。在此流程中，在与钱包启动流程之前，凭据颁发者首先执行准备凭据颁发所需的步骤。

颁发者

Issuer 是一个组件，用于方便凭据颁发请求的授权和提交。它由两个组件组成：

IssuanceAuthorizer：一个负责与授权服务器进行所有交互以授权凭据颁发请求的组件。
IssuanceRequester：一个负责与凭据颁发者进行所有交互以提交凭据颁发请求的组件。

初始化一个颁发者

import OpenID4VCI

let credentialIdentifier = try CredentialIdentifier(value: "https://....")
let credentialIssuerIdentifier = try CredentialIssuerId(CREDENTIAL_ISSUER_PUBLIC_URL)
let offer: CredentialOffer = ...
let config: OpenId4VCIConfig = ...

let issuer = try Issuer(
    authorizationServerMetadata: offer.authorizationServerMetadata,
    issuerMetadata: offer.credentialIssuerMetadata,
    config: config
)

通过授权码流程授权请求

给定一个 Issuer，使用授权码流程来授权颁发请求。

import OpenID4VCI

let parPlaced = await issuer.pushAuthorizationCodeRequest(
  credentialOffer: offer
)

if case let .success(request) = parPlaced,
   case let .par(parRequested) = request {
      
    let authorizationCode = ...
    let issuanceAuthorization: IssuanceAuthorization = .authorizationCode(authorizationCode: authorizationCode)
    let unAuthorized = await issuer.handleAuthorizationCode(
        parRequested: request,
        authorizationCode: issuanceAuthorization
      )
      
    switch unAuthorized {
      case .success(let request):
        let authorizedRequest = await issuer.requestAccessToken(authorizationCode: request)
        
        if case let .success(authorized) = authorizedRequest,
           case let .noProofRequired(token) = authorized {
          print("\(token.accessToken)")
        }
        
      case .failure:
        throw ...
      }
    }
    throw ...
}

通过预授权码流程授权请求

给定一个 Issuer，使用预授权码流程来授权颁发请求。

import OpenID4VCI

let issuer: Issuer = ...
let preAuthorizationCode = ... // pre-authorization code as contained in a credential offer 
let authorizedRequest = await issuer.authorizeWithPreAuthorizationCode(
    credentialOffer: ...,
    authorizationCode: ...,
    clientId: ...,
    transactionCode: ...
  )

请求单个凭据颁发

给定一个 authorizedRequest 和一个 Issuer，可以按以下方式放置单个凭据颁发请求：

import OpenID4VCI

let payload: IssuanceRequestPayload = .configurationBased(
  credentialConfigurationIdentifier: ...
)

let requestOutcome = try await issuer.request(
    proofRequest: ...,
    bindingKeys: ..., // SigningKeyProxy array
    requestPayload: payload,
    responseEncryptionSpecProvider:  { 
        Issuer.createResponseEncryptionSpec($0) 
    }
)

switch requestOutcome {

}

您还可以查看单元测试以获取更多用法示例。

支持的功能

授权端点

规范定义了（第 5.1.1 节）当使用授权码流程时，可以使用 authorization_details 参数请求凭据的颁发。当前版本的库不支持此功能。它仅支持在授权端点中使用 scope 参数请求颁发。

令牌端点

规范定义了（第 6.2 节）在成功响应令牌后，如果在授权端点中使用了 authorization_details 参数，则响应中会包含 authorization_details。当前版本的库不解析/使用此响应属性。

凭据请求

当前版本的库实现了与颁发者的凭据端点和延迟凭据端点端点的集成。

注意： 凭据请求的属性 credential_identifier 尚未支持。

凭据格式配置文件

OpenId4VCI 规范定义了多个扩展点，以适应凭据格式的差异。当前版本的库完全支持 ISO mDL 配置文件，并初步支持 IETF SD-JWT VC 配置文件。

证明类型

OpenId4VCI 规范（草案 14）定义了可以包含在凭据颁发请求中的证明，特别是 JWT 证明类型。当前版本的库支持 JWT 证明类型。

注释

以上所有示例都位于该库的测试目标中。

如何贡献

我们欢迎大家为本项目做贡献。为确保流程对所有参与者都顺利，请遵循 CONTRIBUTING.md 中的指南。

许可证

第三方组件许可证

JOSE 支持: JOSESwift
JSON 支持: SwiftyJSON

许可证详情

根据 Apache License, Version 2.0（“许可证”）授权；除非符合许可证，否则您不得使用此文件。您可以在以下位置获得许可证的副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或以书面形式同意，否则按“原样”分发的软件不附带任何形式的明示或暗示的保证或条件。有关管理权限和限制的特定语言，请参见许可证。