cms-hte-ial2-reader 0.0.2__py3-none-any.whl

cms_hte_ial2_reader-0.0.2.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: cms-hte-ial2-reader
+Version: 0.0.2
+Summary: Reads IAL2 token, verifies digital signature and returns FHIR Patient resource
+Author-email: Imran Qureshi <imran.qureshi@bwell.com>
+Project-URL: Repository, https://github.com/icanbwell/cms-hte-ial2-reader
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: cryptography>=43.0.0
+Requires-Dist: fhirschemapy>=0.0.11
+Dynamic: license-file
+
+# cms-hte-ial2-reader
+
+Reads IAL2 token, verifies digital signature and returns FHIR Patient resource
+
+Accepts a signed JWT (ID Token) from a Credential Service Provider (CSP),
+verifies the signature via JWKS, extracts demographics per the CSP payload
+specification V7.1, and returns a FHIR R4 Patient resource.
+
+## Usage
+
+```python
+from cmshteial2reader import IAL2Extractor, TokenVerifier
+
+verifier = TokenVerifier(
+    jwks_uri="https://idp.example.com/.well-known/jwks.json",
+    audience="my-client-id",
+)
+extractor = IAL2Extractor(verifier=verifier)
+patient = await extractor.extract(token_string)
+# patient is a FHIR R4 Patient resource dict
+```
+
+To accept tokens from any issuer on an explicit allow list (rather than a
+single pinned issuer), use `MultiIssuerTokenVerifier` in place of
+`TokenVerifier`:
+
+```python
+from cmshteial2reader import IAL2Extractor, MultiIssuerTokenVerifier
+
+verifier = MultiIssuerTokenVerifier.from_env(audience="my-client-id")
+extractor = IAL2Extractor(verifier=verifier)
+patient = await extractor.extract(token_string)
+```
+
+`MultiIssuerTokenVerifier.from_env` reads its whitelist of trusted JWKS URLs
+from the `IAL2_ALLOWED_JWKS_URLS` environment variable (comma-separated).
+
+## Quickstart
+- `make init` to set up the local dev environment.
+- `make up` to start the Docker dev stack.
+- `make tests` to run tests in the dev container.
+
+## Common Tasks
+- `make shell` to open a shell in the dev container.
+- `make run-pre-commit` to run linting and formatting hooks.
+- `make build` to build the package artifacts.
+
+## Publishing
+- Set a token: `export TWINE_PASSWORD=pypi-xxx`
+- `make package` to publish to PyPI or `make testpackage` for TestPyPI.
+
+## Project Metadata
+- Repo: https://github.com/icanbwell/cms-hte-ial2-reader
+- Author: Imran Qureshi <imran.qureshi@bwell.com>

cms_hte_ial2_reader-0.0.2.dist-info/RECORD

@@ -0,0 +1,13 @@
+cms_hte_ial2_reader-0.0.2.dist-info/licenses/LICENSE,sha256=8bqmh5rx8pyajtpI25opYOAsjey5tYgml_i-v1IzlHI,11928
+cms_hte_ial2_reader-0.0.2.dist-info/licenses/NOTICE,sha256=xB4gR4vwAHrDAixnYEexN3a2j3jVR0KvCB2gRKovp7k,1289
+cmshteial2reader/__init__.py,sha256=0hdBjWKIt12dc29P98_vC9IkZnWmvDtJvtH1YPRq6K4,787
+cmshteial2reader/claims_model.py,sha256=PsrmcSECbgvh3ykVaA1gXE44Atzec4maQFW3DNoPNO0,7109
+cmshteial2reader/fhir_converter.py,sha256=gPTLngLUt0_V1de0Ux3DhmGH_qblRUJf9eigAo2SRwY,8444
+cmshteial2reader/ial2_extractor.py,sha256=1XprEVgK6Kb-J9F1HNS2qCTmf6bRD1bomMXxxeeVkX8,2962
+cmshteial2reader/multi_issuer_verifier.py,sha256=ivFP7X9YoURVQswCx9JYGilXZXAjDjx10SGgZt7EPIs,7374
+cmshteial2reader/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cmshteial2reader/token_verifier.py,sha256=GqXdSmE6JDmpogb9Z7lZauWHIHnfjwV2WciEG8jKC_w,7299
+cms_hte_ial2_reader-0.0.2.dist-info/METADATA,sha256=JMEsTtL03IPOg1w3nrFsMxquMoLBid6y0PG0MbGBhxg,2521
+cms_hte_ial2_reader-0.0.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+cms_hte_ial2_reader-0.0.2.dist-info/top_level.txt,sha256=kZHQ9HpkkY1Ei3nv7TiSP_XPeMD-lz0FnXqIqFware0,17
+cms_hte_ial2_reader-0.0.2.dist-info/RECORD,,

cms_hte_ial2_reader-0.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cms_hte_ial2_reader-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,215 @@
+Copyright 2026 b.well Connected Health, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cms_hte_ial2_reader-0.0.2.dist-info/licenses/NOTICE

@@ -0,0 +1,10 @@
+cms-hte-ial2-reader
+Copyright 2026 b.well Connected Health, Inc.
+
+This product includes software developed by b.well Connected Health, Inc. (https://www.bwell.com).
+
+Portions of this software may incorporate third-party open source components; see THIRD-PARTY-NOTICES.md for a complete list of those components and their respective licenses.
+
+b.well Connected Health, Inc. is not affiliated with, and this software is not endorsed or certified by, the Centers for Medicare & Medicaid Services (CMS) or HL7 International. This software verifies signed JWT ID Tokens issued by third-party Credential Service Providers (CSPs) at NIST 800-63-3 Identity Assurance Level 2 (IAL2) and extracts demographics per those CSPs' payload specifications into a FHIR R4 Patient resource; references to CMS, IAL2, JWT/JWKS, and FHIR are solely for interoperability description and do not imply endorsement by, or affiliation with, any CSP, NIST, or HL7 International.
+
+This software may be subject to U.S. export control laws, including the Export Administration Regulations (EAR). You may not use, export, or re-export this software in violation of applicable export laws, or to any country, entity, or individual subject to U.S. sanctions or listed on a U.S. government restricted- or denied-party list.

cms_hte_ial2_reader-0.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+cmshteial2reader

cmshteial2reader/__init__.py

@@ -0,0 +1,23 @@
+"""cmshteial2reader: Extract and verify IAL2 token demographics as FHIR Patient resources.
+
+Accepts a signed JWT (ID Token) from a Credential Service Provider (CSP),
+verifies the signature via JWKS, extracts demographics per the CSP payload
+specification V7.1, and returns a FHIR R4 Patient resource.
+"""
+
+from .claims_model import IAL2Address, IAL2Claims, IAL2LegalId
+from .fhir_converter import IAL2ToFhirConverter
+from .ial2_extractor import IAL2Extractor
+from .multi_issuer_verifier import MultiIssuerTokenVerifier
+from .token_verifier import TokenVerificationError, TokenVerifier
+
+__all__ = [
+    "IAL2Address",
+    "IAL2Claims",
+    "IAL2Extractor",
+    "IAL2LegalId",
+    "IAL2ToFhirConverter",
+    "MultiIssuerTokenVerifier",
+    "TokenVerificationError",
+    "TokenVerifier",
+]

cmshteial2reader/claims_model.py

@@ -0,0 +1,211 @@
+"""Data models for IAL2 token claims per CSP Payload Specification V7.1.
+
+Handles field-name aliases across CSPs (e.g. name_first vs given_name)
+and normalizes them into a single canonical representation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class IAL2Address:
+    """A physical address extracted from an IAL2 token.
+
+    Attributes:
+        address_line1: Primary street address.
+        address_line2: Secondary address line (apt, suite, etc.).
+        city: City or locality.
+        state: State, province, or region.
+        postal_code: ZIP or postal code.
+        country: Country.
+        full_address: Composite formatted address string.
+    """
+
+    address_line1: str | None = None
+    address_line2: str | None = None
+    city: str | None = None
+    state: str | None = None
+    postal_code: str | None = None
+    country: str | None = None
+    full_address: str | None = None
+
+
+@dataclass
+class IAL2LegalId:
+    """A government-issued legal identity document.
+
+    Attributes:
+        issuer: Issuing authority (e.g. state DMV, federal government).
+        id_type: Type of document (e.g. drivers_license, passport).
+        identifier: The document number/identifier.
+    """
+
+    issuer: str | None = None
+    id_type: str | None = None
+    identifier: str | None = None
+
+
+@dataclass
+class IAL2Claims:
+    """Normalized demographic claims from an IAL2 token.
+
+    Fields follow the CSP Payload Specification V7.1 (Feb 2026).
+    Alias resolution (e.g. given_name -> name_first) happens in from_token_claims().
+    """
+
+    # OIDC standard claims
+    iss: str = ""
+    sub: str = ""
+    aud: str = ""
+    exp: int = 0
+    iat: int = 0
+    jti: str = ""
+    at_hash: str | None = None
+    auth_time: int | None = None
+    identity_assurance_level: str | None = None
+
+    # Core person attributes
+    name_first: str = ""
+    name_middle: str | None = None
+    name_last: str = ""
+    name_full: str | None = None
+    name_historical: list[str] | None = None
+    birth_date: str = ""
+    sex_legal: str | None = None
+
+    # Address information
+    address: IAL2Address | None = None
+    address_historical: list[IAL2Address] | None = None
+
+    # Contact information
+    email: str | None = None
+    phone_number: str | None = None
+    phone_number_historical: list[str] | None = None
+
+    # Legal identifiers
+    uuid: str | None = None
+    ssn_itin: str | None = None
+    ssn_itin_short: str | None = None
+    legal_id: IAL2LegalId | None = None
+    suffix: str | None = None
+
+    @classmethod
+    def from_token_claims(cls, claims: dict[str, Any]) -> IAL2Claims:
+        """Create an IAL2Claims instance from raw JWT claims.
+
+        Resolves field-name aliases used by different CSPs:
+          - given_name -> name_first
+          - middle_name -> name_middle
+          - last_name -> name_last
+          - street_address -> address_line1
+          - locality -> city
+          - region -> state
+          - postal_code / code_postal -> postal_code
+          - formatted -> full_address
+        """
+        address = _extract_address(claims)
+        historical_addresses = _extract_historical_addresses(
+            claims.get("address_historical")
+        )
+        legal_id = _extract_legal_id(claims)
+
+        return cls(
+            # OIDC standard
+            iss=claims.get("iss", ""),
+            sub=claims.get("sub", ""),
+            aud=claims.get("aud", ""),
+            exp=claims.get("exp", 0),
+            iat=claims.get("iat", 0),
+            jti=claims.get("jti", ""),
+            at_hash=claims.get("at_hash"),
+            auth_time=claims.get("auth_time"),
+            identity_assurance_level=claims.get("identity_assurance_level"),
+            # Core person
+            name_first=claims.get("name_first") or claims.get("given_name", ""),
+            name_middle=claims.get("name_middle") or claims.get("middle_name"),
+            name_last=claims.get("name_last") or claims.get("last_name", ""),
+            name_full=claims.get("name_full"),
+            name_historical=claims.get("name_historical"),
+            birth_date=claims.get("birth_date") or claims.get("date_birth", ""),
+            sex_legal=claims.get("sex_legal") or claims.get("gender"),
+            suffix=claims.get("suffix"),
+            # Address
+            address=address,
+            address_historical=historical_addresses,
+            # Contact
+            email=claims.get("email"),
+            phone_number=claims.get("phone_number"),
+            phone_number_historical=claims.get("phone_number_historical"),
+            # Legal identifiers
+            uuid=claims.get("UUID") or claims.get("uuid"),
+            ssn_itin=claims.get("ssn_itin"),
+            ssn_itin_short=claims.get("ssn_itin_short"),
+            legal_id=legal_id,
+        )
+
+
+def _extract_address(claims: dict[str, Any]) -> IAL2Address | None:
+    """Extract the primary address from claims, resolving aliases."""
+    line1 = claims.get("address_line1") or claims.get("street_address")
+    city = claims.get("city") or claims.get("locality")
+    state = claims.get("state") or claims.get("region")
+    postal = claims.get("postal_code") or claims.get("code_postal")
+
+    if not any([line1, city, state, postal]):
+        return None
+
+    return IAL2Address(
+        address_line1=line1,
+        address_line2=claims.get("address_line2"),
+        city=city,
+        state=state,
+        postal_code=postal,
+        country=claims.get("country"),
+        full_address=claims.get("full_address") or claims.get("formatted"),
+    )
+
+
+def _extract_historical_addresses(
+    raw: Any,
+) -> list[IAL2Address] | None:
+    """Parse historical addresses from the claims payload."""
+    if not raw or not isinstance(raw, list):
+        return None
+
+    addresses: list[IAL2Address] = []
+    for entry in raw:
+        if not isinstance(entry, dict):
+            continue
+
+        addresses.append(
+            IAL2Address(
+                address_line1=entry.get("address_line1") or entry.get("street_address"),
+                address_line2=entry.get("address_line2"),
+                city=entry.get("city") or entry.get("locality"),
+                state=entry.get("state") or entry.get("region"),
+                postal_code=entry.get("postal_code") or entry.get("code_postal"),
+                country=entry.get("country"),
+                full_address=entry.get("full_address") or entry.get("formatted"),
+            )
+        )
+    return addresses if addresses else None
+
+
+def _extract_legal_id(claims: dict[str, Any]) -> IAL2LegalId | None:
+    """Extract legal identity document info from claims."""
+    legal_id_raw = claims.get("legal_id") or claims.get("legal_id_issuer")
+    if not legal_id_raw:
+        return None
+
+    if isinstance(legal_id_raw, dict):
+        return IAL2LegalId(
+            issuer=legal_id_raw.get("issuer"),
+            id_type=legal_id_raw.get("type"),
+            identifier=legal_id_raw.get("identifier"),
+        )
+
+    # If it's a string, treat it as the issuer identifier
+    return IAL2LegalId(issuer=str(legal_id_raw))

cmshteial2reader/fhir_converter.py

@@ -0,0 +1,267 @@
+"""Converts IAL2 demographic claims into a FHIR R4 Patient resource.
+
+Produces a dict conforming to the FHIR R4 Patient resource structure
+(https://hl7.org/fhir/R4/patient.html).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fhirschemapy.R4B.patient import Patient
+
+from .claims_model import IAL2Address, IAL2Claims
+
+# Mapping from CSP sex_legal values to FHIR administrative gender codes
+_SEX_TO_FHIR_GENDER: dict[str, str] = {
+    "male": "male",
+    "m": "male",
+    "female": "female",
+    "f": "female",
+    "other": "other",
+    "unknown": "unknown",
+}
+
+# https://terminology.hl7.org/CodeSystem-v2-0203.html
+_IDENTIFIER_TYPE_CODING_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0203"
+_SSN_IDENTIFIER_SYSTEM = "http://hl7.org/fhir/sid/us-ssn"
+
+# FHIR Identifier.type coding codes (from the v2-0203 code system above)
+_IDENTIFIER_CODE_RESOURCE_IDENTIFIER = "RI"
+_IDENTIFIER_CODE_SOCIAL_SECURITY_NUMBER = "SS"
+_IDENTIFIER_CODE_DRIVERS_LICENSE_NUMBER = "DL"
+
+# FHIR HumanName.use / Address.use / ContactPoint.use values
+_USE_OFFICIAL = "official"
+_USE_HOME = "home"
+_USE_MOBILE = "mobile"
+_USE_OLD = "old"
+
+# FHIR ContactPoint.system values
+_CONTACT_SYSTEM_EMAIL = "email"
+_CONTACT_SYSTEM_PHONE = "phone"
+
+
+class IAL2ToFhirConverter:
+    """Converts IAL2Claims into a FHIR R4 Patient resource dictionary."""
+
+    def convert(self, claims: IAL2Claims) -> dict[str, Any]:
+        """Convert IAL2 claims to a FHIR Patient resource.
+
+        Args:
+            claims: The normalized IAL2 demographic claims.
+
+        Returns:
+            A dictionary representing a FHIR R4 Patient resource, validated
+            through fhirschemapy.
+
+        Raises:
+            pydantic.ValidationError: If the built resource doesn't conform
+                to the FHIR R4 Patient schema.
+        """
+        patient: dict[str, Any] = {
+            "resourceType": "Patient",
+        }
+
+        # Identifiers
+        identifiers = self._build_identifiers(claims)
+        if identifiers:
+            patient["identifier"] = identifiers
+
+        # Name
+        names = self._build_names(claims)
+        if names:
+            patient["name"] = names
+
+        # Birth date
+        if claims.birth_date:
+            patient["birthDate"] = claims.birth_date
+
+        # Gender
+        if claims.sex_legal:
+            gender = _SEX_TO_FHIR_GENDER.get(claims.sex_legal.lower(), "unknown")
+            patient["gender"] = gender
+
+        # Telecom (email, phone)
+        telecoms = self._build_telecoms(claims)
+        if telecoms:
+            patient["telecom"] = telecoms
+
+        # Address
+        addresses = self._build_addresses(claims)
+        if addresses:
+            patient["address"] = addresses
+
+        validated = Patient.model_validate(patient)
+        result: dict[str, Any] = validated.model_dump(exclude_none=True, by_alias=True)
+        return result
+
+    @staticmethod
+    def _build_identifiers(claims: IAL2Claims) -> list[dict[str, Any]]:
+        """Build FHIR Identifier entries from claims."""
+        identifiers: list[dict[str, Any]] = []
+
+        if claims.uuid:
+            identifiers.append(
+                {
+                    "system": claims.iss,
+                    "value": claims.uuid,
+                    "type": {
+                        "coding": [
+                            {
+                                "system": _IDENTIFIER_TYPE_CODING_SYSTEM,
+                                "code": _IDENTIFIER_CODE_RESOURCE_IDENTIFIER,
+                                "display": "Resource identifier",
+                            }
+                        ]
+                    },
+                }
+            )
+
+        if claims.ssn_itin:
+            identifiers.append(
+                {
+                    "system": _SSN_IDENTIFIER_SYSTEM,
+                    "value": claims.ssn_itin,
+                    "type": {
+                        "coding": [
+                            {
+                                "system": _IDENTIFIER_TYPE_CODING_SYSTEM,
+                                "code": _IDENTIFIER_CODE_SOCIAL_SECURITY_NUMBER,
+                                "display": "Social Security number",
+                            }
+                        ]
+                    },
+                }
+            )
+
+        if claims.legal_id:
+            lid = claims.legal_id
+            identifier_entry: dict[str, Any] = {
+                "type": {
+                    "coding": [
+                        {
+                            "system": _IDENTIFIER_TYPE_CODING_SYSTEM,
+                            "code": _IDENTIFIER_CODE_DRIVERS_LICENSE_NUMBER,
+                            "display": "Driver's license number",
+                        }
+                    ]
+                },
+            }
+            if lid.identifier:
+                identifier_entry["value"] = lid.identifier
+            if lid.issuer:
+                identifier_entry["assigner"] = {"display": lid.issuer}
+            identifiers.append(identifier_entry)
+
+        return identifiers
+
+    @staticmethod
+    def _build_names(claims: IAL2Claims) -> list[dict[str, Any]]:
+        """Build FHIR HumanName entries from claims."""
+        names: list[dict[str, Any]] = []
+
+        # Official / current name
+        official: dict[str, Any] = {"use": _USE_OFFICIAL}
+        if claims.name_last:
+            official["family"] = claims.name_last
+        given: list[str] = []
+        if claims.name_first:
+            given.append(claims.name_first)
+        if claims.name_middle:
+            given.append(claims.name_middle)
+        if given:
+            official["given"] = given
+        if claims.suffix:
+            official["suffix"] = [claims.suffix]
+        if claims.name_full:
+            official["text"] = claims.name_full
+        if official.get("family") or official.get("given"):
+            names.append(official)
+
+        # Historical names
+        if claims.name_historical:
+            for hist_name in claims.name_historical:
+                names.append(
+                    {
+                        "use": _USE_OLD,
+                        "text": hist_name,
+                    }
+                )
+
+        return names
+
+    @staticmethod
+    def _build_telecoms(claims: IAL2Claims) -> list[dict[str, Any]]:
+        """Build FHIR ContactPoint entries from claims."""
+        telecoms: list[dict[str, Any]] = []
+
+        if claims.email:
+            telecoms.append(
+                {
+                    "system": _CONTACT_SYSTEM_EMAIL,
+                    "value": claims.email,
+                    "use": _USE_HOME,
+                }
+            )
+
+        if claims.phone_number:
+            telecoms.append(
+                {
+                    "system": _CONTACT_SYSTEM_PHONE,
+                    "value": claims.phone_number,
+                    "use": _USE_MOBILE,
+                }
+            )
+
+        if claims.phone_number_historical:
+            for phone in claims.phone_number_historical:
+                telecoms.append(
+                    {
+                        "system": _CONTACT_SYSTEM_PHONE,
+                        "value": phone,
+                        "use": _USE_OLD,
+                    }
+                )
+
+        return telecoms
+
+    @staticmethod
+    def _build_addresses(claims: IAL2Claims) -> list[dict[str, Any]]:
+        """Build FHIR Address entries from claims."""
+        addresses: list[dict[str, Any]] = []
+
+        if claims.address:
+            addresses.append(_address_to_fhir(claims.address, use=_USE_HOME))
+
+        if claims.address_historical:
+            for hist_addr in claims.address_historical:
+                addresses.append(_address_to_fhir(hist_addr, use=_USE_OLD))
+
+        return addresses
+
+
+def _address_to_fhir(addr: IAL2Address, *, use: str) -> dict[str, Any]:
+    """Convert an IAL2Address to a FHIR Address dict."""
+    fhir_addr: dict[str, Any] = {"use": use}
+
+    lines: list[str] = []
+    if addr.address_line1:
+        lines.append(addr.address_line1)
+    if addr.address_line2:
+        lines.append(addr.address_line2)
+    if lines:
+        fhir_addr["line"] = lines
+
+    if addr.city:
+        fhir_addr["city"] = addr.city
+    if addr.state:
+        fhir_addr["state"] = addr.state
+    if addr.postal_code:
+        fhir_addr["postalCode"] = addr.postal_code
+    if addr.country:
+        fhir_addr["country"] = addr.country
+    if addr.full_address:
+        fhir_addr["text"] = addr.full_address
+
+    return fhir_addr

cmshteial2reader/ial2_extractor.py

@@ -0,0 +1,97 @@
+"""Main orchestrator for IAL2 token extraction.
+
+Combines token verification and FHIR conversion into a single
+entry point.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Protocol
+
+from .claims_model import IAL2Claims
+from .fhir_converter import IAL2ToFhirConverter
+
+logger = logging.getLogger(__name__)
+
+
+class TokenVerifierProtocol(Protocol):
+    """Structural interface for anything IAL2Extractor can verify tokens with.
+
+    Both TokenVerifier (single issuer) and MultiIssuerTokenVerifier
+    (whitelisted issuers) satisfy this without inheritance.
+    """
+
+    async def verify(self, token: str) -> dict[str, Any]: ...
+
+
+class IAL2Extractor:
+    """Accepts an IAL2 JWT, verifies it, and returns a FHIR Patient resource.
+
+    Args:
+        verifier: A TokenVerifier (single issuer) or MultiIssuerTokenVerifier
+            (whitelisted issuers) for signature validation.
+        converter: An IAL2ToFhirConverter instance. If None, a default
+            converter is created.
+
+    Example::
+
+        verifier = TokenVerifier(
+            jwks_uri="https://idp.example.com/.well-known/jwks.json",
+            audience="my-client-id",
+        )
+        extractor = IAL2Extractor(verifier=verifier)
+        patient = await extractor.extract(token_string)
+        # patient is a FHIR R4 Patient resource dict
+    """
+
+    def __init__(
+        self,
+        *,
+        verifier: TokenVerifierProtocol,
+        converter: IAL2ToFhirConverter | None = None,
+    ) -> None:
+        self._verifier = verifier
+        self._converter = converter or IAL2ToFhirConverter()
+
+    async def extract(self, token: str) -> dict[str, Any]:
+        """Verify an IAL2 token and return a FHIR Patient resource.
+
+        Args:
+            token: The encoded JWT string from the CSP.
+
+        Returns:
+            A FHIR R4 Patient resource as a dictionary.
+
+        Raises:
+            TokenVerificationError: If the token signature or claims
+                are invalid.
+        """
+        logger.debug("Verifying IAL2 token")
+        raw_claims = await self._verifier.verify(token)
+
+        logger.debug("Extracting claims from verified token")
+        claims = IAL2Claims.from_token_claims(raw_claims)
+
+        logger.debug("Converting claims to FHIR Patient resource")
+        patient = self._converter.convert(claims)
+
+        return patient
+
+    async def extract_claims(self, token: str) -> IAL2Claims:
+        """Verify an IAL2 token and return the normalized claims.
+
+        Useful when you need the structured claims without FHIR conversion.
+
+        Args:
+            token: The encoded JWT string from the CSP.
+
+        Returns:
+            An IAL2Claims dataclass with normalized demographics.
+
+        Raises:
+            TokenVerificationError: If the token signature or claims
+                are invalid.
+        """
+        raw_claims = await self._verifier.verify(token)
+        return IAL2Claims.from_token_claims(raw_claims)

cmshteial2reader/multi_issuer_verifier.py

@@ -0,0 +1,198 @@
+"""Multi-issuer JWT verification restricted to a whitelist of JWKS URLs.
+
+Resolves an incoming token's issuer via OIDC discovery, then only proceeds
+with signature verification if the discovered JWKS URL is on an explicit
+allow list -- an unrecognized issuer is rejected before any signing key is
+fetched.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import os
+import socket
+from typing import Any
+from urllib.parse import urlparse
+
+import jwt
+
+from .token_verifier import TokenVerificationError, TokenVerifier
+
+_IpAddress = ipaddress.IPv4Address | ipaddress.IPv6Address
+
+ALLOWED_JWKS_URLS_ENV_VAR = "IAL2_ALLOWED_JWKS_URLS"
+
+
+class MultiIssuerTokenVerifier:
+    """Verifies IAL2 JWTs from any issuer whose JWKS URL is whitelisted.
+
+    Unlike TokenVerifier, which is pinned to a single jwks_uri, this class
+    accepts tokens from multiple issuers by resolving each token's issuer
+    via OIDC discovery and checking the discovered JWKS URL against an
+    explicit allow list before trusting it.
+
+    Args:
+        audience: Expected ``aud`` claim value, applied to every issuer.
+        allowed_jwks_uris: JWKS URLs this instance will trust.
+        algorithms: Allowed signing algorithms. Defaults to RS256.
+
+    Example::
+
+        verifier = MultiIssuerTokenVerifier.from_env(audience="my-client-id")
+        claims = await verifier.verify(token_string)
+    """
+
+    def __init__(
+        self,
+        *,
+        audience: str,
+        allowed_jwks_uris: list[str],
+        algorithms: list[str] | None = None,
+    ) -> None:
+        self._audience = audience
+        self._allowed_jwks_uris = set(allowed_jwks_uris)
+        self._algorithms = algorithms
+        self._verifiers_by_issuer: dict[str, TokenVerifier] = {}
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        audience: str,
+        env_var: str = ALLOWED_JWKS_URLS_ENV_VAR,
+        algorithms: list[str] | None = None,
+    ) -> MultiIssuerTokenVerifier:
+        """Build the verifier from a comma-separated env var of JWKS URLs.
+
+        Args:
+            audience: Expected ``aud`` claim value.
+            env_var: Name of the env var holding the whitelist.
+            algorithms: Allowed signing algorithms.
+
+        Raises:
+            ValueError: If the env var is unset or contains no URLs.
+        """
+        raw = os.environ.get(env_var, "")
+        allowed = [url.strip() for url in raw.split(",") if url.strip()]
+        if not allowed:
+            raise ValueError(f"{env_var} is not set or contains no JWKS URLs")
+        return cls(audience=audience, allowed_jwks_uris=allowed, algorithms=algorithms)
+
+    async def verify(self, token: str) -> dict[str, Any]:
+        """Verify a token from any whitelisted issuer.
+
+        Args:
+            token: The encoded JWT string.
+
+        Returns:
+            The decoded claims dictionary.
+
+        Raises:
+            TokenVerificationError: If the issuer's JWKS URL isn't
+                whitelisted, or the token fails verification.
+        """
+        issuer = self._peek_issuer(token)
+
+        verifier = self._verifiers_by_issuer.get(issuer)
+        if verifier is None:
+            verifier = await self._build_verifier_for_issuer(issuer)
+            self._verifiers_by_issuer[issuer] = verifier
+
+        return await verifier.verify(token)
+
+    @staticmethod
+    def _peek_issuer(token: str) -> str:
+        """Read the ``iss`` claim without verifying the signature.
+
+        This claim is untrusted at this point -- it is only used to select
+        which JWKS URL to check against the whitelist, never to make a
+        trust decision on its own. The real verification happens in
+        TokenVerifier.verify() once the whitelist check passes.
+        """
+        try:
+            unverified = jwt.decode(token, options={"verify_signature": False})
+        except jwt.InvalidTokenError as e:
+            raise TokenVerificationError(f"Could not parse token: {e}") from e
+
+        issuer = unverified.get("iss")
+        if not issuer:
+            raise TokenVerificationError("Token is missing the 'iss' claim")
+        return str(issuer)
+
+    async def _build_verifier_for_issuer(self, issuer: str) -> TokenVerifier:
+        """Discover the issuer's JWKS URL and check it against the whitelist."""
+        pinned_ip = await self._validate_issuer_url(issuer)
+
+        verifier = await TokenVerifier.from_oidc_discovery(
+            discovery_url=f"{issuer.rstrip('/')}/.well-known/openid-configuration",
+            audience=self._audience,
+            issuer=issuer,
+            algorithms=self._algorithms,
+            pinned_ip=pinned_ip,
+        )
+        if verifier.jwks_uri not in self._allowed_jwks_uris:
+            raise TokenVerificationError(
+                f"Issuer '{issuer}' resolved to JWKS URL "
+                f"'{verifier.jwks_uri}', which is not whitelisted"
+            )
+        return verifier
+
+    @staticmethod
+    async def _validate_issuer_url(issuer: str) -> str:
+        """Reject issuer URLs that could be used for SSRF before any
+        discovery or JWKS request is made, and return the validated IP to
+        pin the actual discovery connection to.
+
+        The issuer claim is unverified at this point -- read via
+        _peek_issuer() before signature verification, purely to select a
+        JWKS URL. Without this check, an attacker could set 'iss' to an
+        internal service or cloud metadata endpoint and have this process
+        make a request to it during OIDC discovery. Returning the validated
+        IP (rather than just validating and discarding it) lets the caller
+        pin the actual connection to it, closing the DNS-rebinding window
+        between this check and the request.
+        """
+        parsed = urlparse(issuer)
+        if parsed.scheme != "https":
+            raise TokenVerificationError(f"Issuer URL must use https, got: {issuer!r}")
+
+        hostname = parsed.hostname
+        if not hostname:
+            raise TokenVerificationError(f"Issuer URL is missing a host: {issuer!r}")
+
+        addresses = await MultiIssuerTokenVerifier._resolve_addresses(hostname)
+        for address in addresses:
+            if (
+                address.is_private
+                or address.is_loopback
+                or address.is_link_local
+                or address.is_multicast
+                or address.is_reserved
+                or address.is_unspecified
+            ):
+                raise TokenVerificationError(
+                    f"Issuer '{issuer}' resolves to a non-public address "
+                    f"({address}); rejected"
+                )
+        return str(addresses[0])
+
+    @staticmethod
+    async def _resolve_addresses(hostname: str) -> list[_IpAddress]:
+        """Resolve a hostname to the IP address(es) it points to.
+
+        Guards against DNS rebinding: a hostname that looks external in
+        text form can still resolve to an internal address.
+        """
+        try:
+            return [ipaddress.ip_address(hostname)]
+        except ValueError:
+            pass
+
+        try:
+            infos = await asyncio.to_thread(socket.getaddrinfo, hostname, None)
+        except socket.gaierror as e:
+            raise TokenVerificationError(
+                f"Could not resolve issuer host '{hostname}': {e}"
+            ) from e
+        return [ipaddress.ip_address(info[4][0]) for info in infos]

cmshteial2reader/token_verifier.py

@@ -0,0 +1,205 @@
+"""JWT signature verification for IAL2 tokens using JWKS.
+
+Fetches the CSP's public keys from their OIDC discovery endpoint
+and verifies the token signature, expiration, and audience.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import http.client
+import json
+import logging
+import socket
+import ssl
+from typing import Any
+from urllib.parse import urlparse
+from urllib.request import urlopen
+
+import jwt
+from jwt import PyJWKClient
+
+logger = logging.getLogger(__name__)
+
+
+class TokenVerificationError(Exception):
+    """Raised when an IAL2 token fails signature or claims verification."""
+
+
+class _PinnedHTTPSConnection(http.client.HTTPSConnection):
+    """An HTTPSConnection that dials a pre-resolved IP instead of
+    re-resolving its host via DNS, while still using that original host for
+    TLS SNI and certificate verification.
+
+    Used to close the DNS-rebinding TOCTOU window between validating a
+    hostname's resolved address and actually connecting to it: a plain
+    HTTPSConnection re-resolves the hostname at connect() time, so an
+    attacker controlling that hostname's DNS could serve a different
+    (internal) address than the one that was validated moments earlier.
+    """
+
+    # Declared here for mypy: real attributes set by HTTPSConnection.__init__
+    # (typeshed doesn't expose them, since they're conventionally private).
+    _context: ssl.SSLContext
+    source_address: tuple[str, int] | None
+
+    def __init__(self, host: str, pinned_ip: str, **kwargs: Any) -> None:
+        super().__init__(host, **kwargs)
+        self._pinned_ip = pinned_ip
+
+    def connect(self) -> None:
+        sock = socket.create_connection(
+            (self._pinned_ip, self.port), self.timeout, self.source_address
+        )
+        self.sock = self._context.wrap_socket(sock, server_hostname=self.host)
+
+
+def _fetch_json_pinned(
+    url: str, pinned_ip: str, *, timeout: float = 10.0
+) -> dict[str, Any]:
+    """Fetch and parse JSON from `url`, connecting to `pinned_ip` rather
+    than letting the request re-resolve the URL's hostname via DNS."""
+    parsed = urlparse(url)
+    conn = _PinnedHTTPSConnection(
+        parsed.hostname or "", pinned_ip, port=parsed.port, timeout=timeout
+    )
+    try:
+        conn.request("GET", parsed.path or "/", headers={"Accept": "application/json"})
+        response = conn.getresponse()
+        body = response.read()
+    finally:
+        conn.close()
+    result: dict[str, Any] = json.loads(body)
+    return result
+
+
+class TokenVerifier:
+    """Verifies IAL2 JWT tokens against a CSP's JWKS endpoint.
+
+    Args:
+        jwks_uri: URL of the JWKS endpoint (e.g.
+            ``https://idp.example.com/.well-known/jwks.json``).
+        audience: Expected ``aud`` claim value.
+        issuer: Expected ``iss`` claim value. If provided, the token's
+            issuer must match exactly.
+        algorithms: Allowed signing algorithms. Defaults to RS256.
+    """
+
+    def __init__(
+        self,
+        *,
+        jwks_uri: str,
+        audience: str,
+        issuer: str | None = None,
+        algorithms: list[str] | None = None,
+    ) -> None:
+        self._jwks_uri = jwks_uri
+        self._audience = audience
+        self._issuer = issuer
+        self._algorithms = algorithms or ["RS256"]
+        self._jwks_client = PyJWKClient(jwks_uri)
+
+    @property
+    def jwks_uri(self) -> str:
+        """The JWKS endpoint this verifier fetches signing keys from."""
+        return self._jwks_uri
+
+    async def verify(self, token: str) -> dict[str, Any]:
+        """Verify the token signature and standard claims.
+
+        Args:
+            token: The encoded JWT string.
+
+        Returns:
+            The decoded claims dictionary.
+
+        Raises:
+            TokenVerificationError: If the token is invalid, expired,
+                or fails audience/issuer checks.
+        """
+        return await asyncio.to_thread(self._verify_sync, token)
+
+    def _verify_sync(self, token: str) -> dict[str, Any]:
+        """Blocking body of verify() -- PyJWT/PyJWKClient have no async API,
+        so verify() offloads this to a thread instead of blocking the event
+        loop for the JWKS fetch (network I/O) this does internally."""
+        try:
+            signing_key = self._jwks_client.get_signing_key_from_jwt(token)
+
+            decoded: dict[str, Any] = jwt.decode(
+                token,
+                signing_key.key,
+                algorithms=self._algorithms,
+                audience=self._audience,
+                issuer=self._issuer,
+                options={
+                    "require": ["exp", "iat", "iss", "sub", "aud", "jti"],
+                },
+            )
+            return decoded
+
+        except jwt.ExpiredSignatureError as e:
+            raise TokenVerificationError(f"Token has expired: {e}") from e
+        except jwt.InvalidAudienceError as e:
+            raise TokenVerificationError(f"Invalid audience: {e}") from e
+        except jwt.InvalidIssuerError as e:
+            raise TokenVerificationError(f"Invalid issuer: {e}") from e
+        except jwt.PyJWKClientError as e:
+            raise TokenVerificationError(
+                f"Failed to fetch signing key from JWKS: {e}"
+            ) from e
+        except jwt.InvalidTokenError as e:
+            raise TokenVerificationError(f"Token verification failed: {e}") from e
+
+    @classmethod
+    async def from_oidc_discovery(
+        cls,
+        *,
+        discovery_url: str,
+        audience: str,
+        issuer: str | None = None,
+        algorithms: list[str] | None = None,
+        pinned_ip: str | None = None,
+    ) -> TokenVerifier:
+        """Create a verifier by fetching the JWKS URI from OIDC discovery.
+
+        Args:
+            discovery_url: The ``/.well-known/openid-configuration`` URL.
+            audience: Expected ``aud`` claim value.
+            issuer: Expected ``iss`` claim value.
+            algorithms: Allowed signing algorithms.
+            pinned_ip: If given, connect to this IP instead of letting the
+                discovery fetch resolve discovery_url's host via DNS. Used
+                by callers (e.g. MultiIssuerTokenVerifier) that have already
+                validated an untrusted host's resolved address and need the
+                actual connection pinned to it, closing the window between
+                that validation and the request.
+
+        Returns:
+            A configured TokenVerifier instance.
+
+        Raises:
+            TokenVerificationError: If discovery metadata cannot be fetched.
+        """
+
+        def _fetch_metadata() -> dict[str, Any]:
+            if pinned_ip:
+                return _fetch_json_pinned(discovery_url, pinned_ip)
+            with urlopen(discovery_url) as response:  # nosec B310
+                result: dict[str, Any] = json.loads(response.read())
+                return result
+
+        try:
+            metadata = await asyncio.to_thread(_fetch_metadata)
+            jwks_uri = metadata["jwks_uri"]
+        except Exception as e:
+            raise TokenVerificationError(
+                f"Failed to fetch OIDC discovery metadata from {discovery_url}: {e}"
+            ) from e
+
+        return cls(
+            jwks_uri=jwks_uri,
+            audience=audience,
+            issuer=issuer or metadata.get("issuer"),
+            algorithms=algorithms,
+        )