fhir-scorecard 0.3.0__tar.gz

fhir_scorecard-0.3.0/.gitattributes

@@ -0,0 +1,30 @@
+
+# CI is the authoritative writer of the drift/availability history: it runs daily from a
+# stable vantage and commits what it observed. Local grade runs overwrite it, which produced a
+# rebase conflict every time. Union-merge keeps both sides rather than failing the rebase; CI
+# rewrites the file wholesale on its next run regardless.
+data/history.json merge=union
+
+# GitHub Actions downloads a source archive for every `uses:` invocation. Keep that archive to
+# the Action runtime instead of shipping the curated registry, the cohort files, the captured
+# fixtures, and the test suite to every consumer. The published dataset lives on the site; a
+# consumer gating their own endpoint has no use for a copy of it.
+/* export-ignore
+/action -export-ignore
+/action.yml -export-ignore
+/CODE_OF_CONDUCT.md -export-ignore
+/LICENSE -export-ignore
+/pyproject.toml -export-ignore
+/README.md -export-ignore
+/SECURITY.md -export-ignore
+/src -export-ignore
+# The vendored design system (stylesheets, fonts, icons) exists to build the site. The Action
+# runtime a consumer downloads runs `check` and never builds a site, so the 50-odd asset files
+# stay out of the archive the same way the dataset does. A checkout has them; the archive is
+# the Action runtime, bounded on purpose.
+/src/fhir_scorecard/assets export-ignore
+
+# Retained specification pages are evidence: keep their bytes exactly as fetched so the
+# SHA-256 values in corpus/SOURCES.json stay true on every checkout. They serve the optional
+# narration layer, not the Action runtime, so they stay out of the archive with the dataset.
+/corpus/** -text

fhir_scorecard-0.3.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner for everything in the repository.
+* @ChelseaKR

fhir_scorecard-0.3.0/.github/ISSUE_TEMPLATE/add-endpoint.yml

@@ -0,0 +1,74 @@
+name: Add or correct an endpoint
+description: Tell us about a public FHIR endpoint we are missing or have wrong
+title: "[endpoint] "
+labels: ["registry"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you. If we recorded your endpoint as unreachable and it is not, we would rather be
+        corrected than counted right. This has already happened once: a live payer endpoint was
+        logged as dead because a middlebox on the probing network intercepted TLS.
+
+        Only public, unauthenticated surfaces are graded. We never register for API access,
+        never authenticate, and never request patient data.
+  - type: input
+    id: organization
+    attributes:
+      label: Organization
+      placeholder: Example Health Plan
+    validations:
+      required: true
+  - type: input
+    id: base_url
+    attributes:
+      label: FHIR base URL
+      description: "The base, not the metadata path. We append /metadata ourselves."
+      placeholder: https://fhir.example.com/r4
+    validations:
+      required: true
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Category
+      description: Grades are only comparable within a category.
+      options:
+        - Payer Patient Access API
+        - Payer Provider Directory API
+        - Provider or health system API
+        - EHR vendor sandbox
+        - Reference or test server
+    validations:
+      required: true
+  - type: dropdown
+    id: fhir_release
+    attributes:
+      label: FHIR release
+      description: Endpoints are graded against the release they intend to serve.
+      options: ["R4", "R5", "STU3"]
+    validations:
+      required: true
+  - type: input
+    id: documentation
+    attributes:
+      label: Public documentation URL
+      description: >
+        Where this base URL is published. This is how we confirm the publisher is who the entry
+        claims, which is what "verified" means here. Entries without it are not added.
+      placeholder: https://example.com/developers
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Anything else
+      description: Corrections to an existing entry, or context on what we got wrong.
+  - type: checkboxes
+    id: confirm
+    attributes:
+      label: Please confirm
+      options:
+        - label: This base URL is intended to be publicly reachable without authentication
+          required: true
+        - label: I am not asking you to authenticate, register, or request patient data
+          required: true

fhir_scorecard-0.3.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,53 @@
+name: Bug report
+description: Something behaves differently than documented
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time. The most useful reports say what you ran,
+        what happened, and what you expected instead.
+
+        If this is a security vulnerability, please do not file it here. See
+        SECURITY.md for how to report it privately.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: >-
+        What you ran and what came back. Paste the output rather than describing it.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected instead
+      description: >-
+        If a rule or spec section says otherwise, quoting it helps a lot.
+    validations:
+      required: true
+  - type: textarea
+    id: input
+    attributes:
+      label: The endpoint
+      description: >-
+        The endpoint URL as it appears in the registry, if it is public.
+      render: text
+    validations:
+      required: false
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: >-
+        The scorecard page or commit you saw this on
+    validations:
+      required: true
+  - type: textarea
+    id: anything-else
+    attributes:
+      label: Anything else
+      description: >-
+        Environment, workarounds you tried, related issues.
+    validations:
+      required: false

fhir_scorecard-0.3.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: How grades are calculated
+    url: https://fhir.chelseakr.com/how-we-grade/
+    about: Every finding code, what it checks, and the spec clause it cites
+  - name: Why some payers cannot be checked publicly
+    url: https://github.com/ChelseaKR/fhir-scorecard/blob/main/docs/payer-verifiability.md
+    about: The write-up, including the measurement errors this project made and corrected

fhir_scorecard-0.3.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,35 @@
+name: Idea or feature request
+description: Suggest something this should do that it does not
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Ideas are welcome, including ones that turn out to be a bad fit. If you
+        are unsure whether something is a bug or intended behavior, open a
+        discussion instead and we can work it out there.
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: >-
+        What are you trying to do that is hard or impossible right now?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you have in mind
+      description: >-
+        A rough shape is fine. Alternatives you considered are useful too.
+    validations:
+      required: false
+  - type: checkboxes
+    id: willing
+    attributes:
+      label: Would you want to build it?
+      description: >-
+        Entirely optional, and a no is a perfectly good answer.
+      options:
+        - label: I would be interested in opening a PR for this
+          required: false

fhir_scorecard-0.3.0/.github/ISSUE_TEMPLATE/remove-or-dispute.yml

@@ -0,0 +1,34 @@
+name: Dispute or remove an entry
+description: Ask us to correct or take down something about your organization
+title: "[dispute] "
+labels: ["registry", "dispute"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This project measures public surfaces and takes a non-adversarial posture. If an entry is
+        wrong, or you would rather not be listed, say so and we will correct or remove it.
+        We do not require you to prove anything first.
+  - type: input
+    id: endpoint
+    attributes:
+      label: Which entry
+      placeholder: "endpoint id or organization name"
+    validations:
+      required: true
+  - type: dropdown
+    id: request
+    attributes:
+      label: What are you asking for
+      options:
+        - Correct a fact
+        - Remove the entry
+        - Something else
+    validations:
+      required: true
+  - type: textarea
+    id: detail
+    attributes:
+      label: Details
+    validations:
+      required: true

fhir_scorecard-0.3.0/.github/allowed_signers

@@ -0,0 +1 @@
+3114598+ChelseaKR@users.noreply.github.com namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIOjn/aI0d9jElCoi7qT4+6j9UmgTH7vLGAqJXiKMoCE

fhir_scorecard-0.3.0/.github/dependabot.yml

@@ -0,0 +1,42 @@
+# Dependency scanning and update PRs (SECURITY-AND-SUPPLY-CHAIN-STANDARD).
+# Runtime dependencies are stdlib-only; this watches the dev toolchain and the
+# SHA-pinned GitHub Actions.
+version: 2
+updates:
+  # `uv`, not `pip`. This project's dependency surface is a PEP 735 `[dependency-groups]`
+  # block resolved into `uv.lock`; `[project] dependencies` is empty. The `pip` ecosystem
+  # does not read `[dependency-groups]`, and a bump that did not also update `uv.lock`
+  # would fail `make verify`, which opens with `uv lock --check`.
+  #
+  # The symptom was silence, not red PRs. Every dependabot pull request ever opened on this
+  # repository - twelve of them, 2026-08-07 to 2026-08-27, on a weekly schedule - is
+  # `github-actions`. Zero are `pip`, across a window in which pytest, mypy, ruff, pip-audit
+  # and hypothesis all released. The dev toolchain the README calls "the whole dependency
+  # surface" was unwatched, and nothing said so.
+  #
+  # `uv` is a documented `package-ecosystem` value: GitHub's Dependabot options reference
+  # lists it, and version updates went generally available for it on 2025-03-13, security
+  # updates on 2025-12-16. `uv.lock` is committed, which is what the ecosystem reads.
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      # `security.yml` pins github/codeql-action/init and github/codeql-action/analyze to
+      # the same commit, and CodeQL refuses to run when the two disagree: "Loaded a
+      # configuration file for version X, but running version Y". Dependabot treats the two
+      # actions as separate dependencies, so ungrouped it opens one PR per action and each
+      # one, in isolation, makes the versions disagree. Both PRs are then born red through
+      # no fault of their own, and whichever merges first leaves `main` red until the other
+      # follows. That happened on the 4.37.6 to 4.37.7 bump (#43 merged before #41) and
+      # again on 4.37.7 to 4.37.8 (#51, #52).
+      #
+      # Grouping them means one PR moves both pins together, which is the only state CodeQL
+      # accepts.
+      codeql-action:
+        patterns:
+          - "github/codeql-action*"

fhir_scorecard-0.3.0/.github/workflows/compliance-bundle.yml

@@ -0,0 +1,182 @@
+name: Compliance report bundle
+
+# The compliance-bundle tier's fulfillment step (docs/compliance-bundle-plan.md): render one
+# buyer's branded evidence reports for a cohort of endpoints, zip them with a manifest, put the
+# archive behind a 30-day capability link, and email the link. GitHub Actions is the on-demand
+# compute, so the tier needs no always-on server.
+#
+# Dispatched by infra/compliance-bundle's post-checkout setup Lambda. It can also be dispatched
+# by hand, on main, to re-run an order: the repair for an undelivered one is a re-run with the
+# same order_ref. Payment is settled before dispatch; this workflow never talks to Stripe.
+#
+# NOTHING ABOUT THE BUYER IS AN INPUT. This repository is public, and GitHub prints each step's
+# environment -- including any value that came from a workflow_dispatch input -- in a run log
+# anyone can read. An earlier draft took the buyer's email address, organization name, endpoint
+# list, and the bundle id (the download capability) as inputs, and would have published every
+# one of them for every order. The only input now is `order_ref`: a random 128-bit name for an
+# object the setup Lambda wrote to the private artifacts bucket. On its own it grants nothing;
+# reading the object needs this workflow's AWS role, which trusts runs on main only. Every value
+# read from the object is registered with ::add-mask:: before any later step can print it, so an
+# error message that happens to quote an address is masked too.
+#
+# Renders from the already-published dataset, never re-probes. A bundle is packaging for the
+# free site's own numbers, not a second measurement, so this fetches
+# https://fhir.chelseakr.com/scorecards.json -- the same file a free visitor reads -- rather than
+# re-grading, which would re-probe every payer's endpoint on every purchase and risk a report
+# that disagrees with the free page for the same endpoint on the same day.
+
+on:
+  workflow_dispatch:
+    inputs:
+      order_ref:
+        description: "32 lowercase hex characters naming a stored order; carries no buyer data"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+# Scoped per order rather than global: GitHub keeps only one pending run per concurrency group,
+# so a shared group would let a third arrival evict a queued, paid order. Scoped to one order, an
+# eviction can only ever drop a duplicate run of the same build. order_ref is safe to name here
+# because it carries nothing.
+concurrency:
+  group: compliance-bundle-${{ inputs.order_ref }}
+  cancel-in-progress: false
+
+jobs:
+  bundle:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      id-token: write # read the order and write the archive through AWS OIDC
+    steps:
+      # A paid order has nowhere to go without these three, so their absence fails the run
+      # (and the run's failure is what tells the owner) rather than building an archive nobody
+      # can reach.
+      - name: Refuse to start without the delivery configuration
+        shell: bash
+        env:
+          ARTIFACTS_BUCKET: ${{ vars.ARTIFACTS_BUCKET }}
+          BUNDLE_API_BASE: ${{ vars.BUNDLE_API_BASE }}
+          SES_FROM: ${{ vars.SES_FROM }}
+          ORDER_REF: ${{ inputs.order_ref }}
+        run: |
+          set -euo pipefail
+          if [ -z "${ARTIFACTS_BUCKET}" ] || [ -z "${BUNDLE_API_BASE}" ] || [ -z "${SES_FROM}" ]; then
+            echo "::error::ARTIFACTS_BUCKET, BUNDLE_API_BASE and SES_FROM must all be set as repository variables before an order can be fulfilled. See docs/compliance-bundle-owner-steps.md."
+            exit 1
+          fi
+          if ! [[ "${ORDER_REF}" =~ ^[a-f0-9]{32}$ ]]; then
+            echo "::error::order_ref must be 32 lowercase hex characters."
+            exit 1
+          fi
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.12"
+      - name: Install the locked environment
+        shell: bash
+        run: |
+          set -euo pipefail
+          uv sync --locked
+
+      - name: Authenticate to AWS
+        uses: aws-actions/configure-aws-credentials@e1253824e5c10ff9df46874f81ed3ec929e19cfd # v6.3.0
+        with:
+          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
+          aws-region: ${{ vars.AWS_REGION || 'us-west-2' }}
+
+      # The object is read into request.json and every buyer-supplied value in it is masked
+      # before anything else runs. The masking happens inside Python reading the file, so no
+      # value ever appears in a step's rendered script or environment block.
+      - name: Collect the order and mask what it holds
+        shell: bash
+        env:
+          ARTIFACTS_BUCKET: ${{ vars.ARTIFACTS_BUCKET }}
+          ORDER_REF: ${{ inputs.order_ref }}
+        run: |
+          set -euo pipefail
+          aws s3 cp "s3://${ARTIFACTS_BUCKET}/compliance-requests/${ORDER_REF}.json" request.json --only-show-errors
+          uv run python -m fhir_scorecard.bundle_order mask request.json
+
+      # The published dataset, fetched fresh rather than trusted from the checkout: the live
+      # site is rebuilt daily on a schedule independent of commits (pages.yml), and a bundle
+      # must render the numbers a buyer could see on fhir.chelseakr.com today. `curl -f` fails
+      # the run on anything but a 2xx: a dataset that could not be read must never render as
+      # "no scorecard is published" for an endpoint that has one.
+      - name: Fetch the published dataset
+        shell: bash
+        run: |
+          set -euo pipefail
+          curl -fsSL --retry 3 --retry-delay 5 -o scorecards.json https://fhir.chelseakr.com/scorecards.json
+
+      - name: Render the bundle
+        shell: bash
+        run: |
+          set -euo pipefail
+          max_endpoints="$(uv run python -m fhir_scorecard.bundle_order cap request.json)"
+          uv run fhir-scorecard bundle --request request.json \
+            --registry data/registry.json --scorecards scorecards.json \
+            --max-endpoints "${max_endpoints}" \
+            --out bundle.zip --plan-out manifest.json
+          included="$(jq '.included' manifest.json)"
+          requested="$(jq '.requested' manifest.json)"
+          {
+            echo "## Compliance report bundle"
+            echo
+            echo "${included} of ${requested} requested endpoints included; the manifest says"
+            echo "what happened to the rest. Nothing identifying the order is shown on this page."
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      # compliance-bundles/ expires after 30 days (main.tf's lifecycle rule). The only way to it
+      # is the download route in infra/compliance-bundle, which presigns per click.
+      - name: Upload the archive behind its capability key
+        shell: bash
+        env:
+          ARTIFACTS_BUCKET: ${{ vars.ARTIFACTS_BUCKET }}
+        run: |
+          set -euo pipefail
+          key="$(uv run python -m fhir_scorecard.bundle_order archive-key request.json)"
+          aws s3 cp bundle.zip "s3://${ARTIFACTS_BUCKET}/${key}" \
+            --content-type application/zip --only-show-errors
+
+      - name: Email the download link
+        shell: bash
+        env:
+          BUNDLE_API_BASE: ${{ vars.BUNDLE_API_BASE }}
+          SES_FROM: ${{ vars.SES_FROM }}
+        run: |
+          set -euo pipefail
+          uv run --with boto3 python -m fhir_scorecard.bundle_order email request.json manifest.json
+
+      # What this may NOT do is name the order: the bundle id is the download credential, and
+      # annotations and run summaries are public on a public repository. This says only that an
+      # order failed and how to repair it.
+      - name: Say that a paid order failed
+        if: ${{ failure() }}
+        shell: bash
+        env:
+          ORDER_REF: ${{ inputs.order_ref }}
+        run: |
+          set -euo pipefail
+          echo "::error::A paid compliance report bundle did not complete. The buyer was told the build had started and nothing else will tell them otherwise. Re-running this workflow on main with the same order_ref is the repair."
+          {
+            echo
+            echo "## A paid order was not delivered"
+            echo
+            echo "- order_ref: \`${ORDER_REF}\` (names the stored order; carries no buyer data)"
+            echo
+            echo "Re-running this workflow with the same order_ref is safe: the archive and the"
+            echo "download link are both keyed on the bundle id inside the stored order, so a"
+            echo "re-run fills the object the buyer's existing link already points at."
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      # Deliberately no upload-artifact step. A run artifact of this repository is published:
+      # every signed-in GitHub account can download it for its whole retention window. bundle.zip
+      # is the paid deliverable and manifest.json and request.json carry the download capability
+      # and the buyer's address.

fhir_scorecard-0.3.0/.github/workflows/live-integrity.yml

@@ -0,0 +1,85 @@
+# Is the site still the site this repository publishes, and is it still being published?
+#
+# grade-and-publish runs `audit-site` on the local site/ directory before the upload,
+# and the deploy job returns. After that nothing has ever looked at the bytes a reader
+# receives. A publish that failed, an upload that dropped an asset, or a Pages setting
+# that stopped serving would leave every gate green while the live site was stale,
+# broken, or gone, and nothing in this repository could tell.
+#
+# This check is narrower than its siblings on purpose. Most of this site is a daily
+# rescore of every live third-party endpoint in the registry, every page footer carries a minute-
+# resolution Generated stamp, and the availability and history pages derive from
+# data/history.json, which CI restores from the capability-history branch rather than
+# from main. Rebuilding that here would mean re-probing every registry endpoint to produce
+# numbers that legitimately differ from the published ones, which is a moving target
+# and would produce noise rather than signal.
+#
+# So it checks what IS a pure function of committed inputs, exactly: all 58 files under
+# src/fhir_scorecard/assets, which write_assets copies verbatim; robots.txt and
+# dataset.schema.json, which are pure functions of the origin string; and the identity
+# half of api/index.json and dataset.csv, meaning the endpoint set and every field that
+# comes from data/registry.json rather than from a probe.
+#
+# One rendered page is read, for four tags. The home page's og:image and twitter:image
+# are site.social_card_url(origin) and nothing else, and og:title, og:description and
+# og:image:alt have to be there. They carry no grade, latency or timestamp, so they are
+# as pure as the two documents above -- and a head naming a card the deployment does not
+# serve is invisible from inside a checkout and blank everywhere the page is shared.
+#
+# Plus the one thing no rebuild would catch and no audit does: the site has to be
+# recent. A site frozen a year ago still audits clean, so api/index.json's generated_at
+# must parse, must not be in the future, and must be inside 48 hours of the run.
+#
+# It reads the network, deliberately, which is why it holds only `contents: read`, is
+# its own workflow, and is not a required check: it grades the deployment, and a
+# deployment that has not happened yet is not a reason to block a merge.
+#
+# Runs daily and on demand (Actions > live integrity sentinel > Run workflow). The cron
+# sits well after grade-and-publish's 14:17 so it reads a settled deployment -- but it
+# also sits five hours and fifty minutes before the next one, and a change merged in that
+# window is on main and not yet on the site. That is 24% of the clock, and the working
+# part of it. It used to be reported as a failure: 1 of the 1 reds this check had by
+# 2026-09-12 was exactly that, #120 merged at 16:24 after the 14:27 publish. The tool now
+# dates the newest commit touching a checked input and calls a site that predates it a
+# pending publish rather than a fault, which is why the checkout below is not shallow.
+name: live integrity sentinel
+
+on:
+  schedule:
+    - cron: "7 20 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: live-integrity
+  cancel-in-progress: false
+
+jobs:
+  verify-live:
+    name: the live site still matches its committed inputs
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: main
+          persist-credentials: false
+          # Full history, because the check asks `git log` when a checked input last
+          # changed and the default depth of 1 cannot answer. A shallow clone grafts its
+          # oldest fetched commit into a parentless root, so at depth 1 every file in the
+          # tree reads as having been added at HEAD: the inputs would date to the newest
+          # commit on main whatever it touched, and any difference at all would be excused
+          # as a publish that has not run yet. verify_live_site.py refuses a parentless
+          # answer for that reason, so a shallow checkout does not weaken the check -- it
+          # loses the distinction entirely and every merge-window difference goes back to
+          # being a spurious red. tests/test_live_integrity_pending_publish.py asserts this.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Compare the live site with this checkout's committed inputs
+        run: python3 tools/verify_live_site.py