docs: 1.8.2 release notes

Address count only, never the address. Separates local waits from the
key-service POST when a lookup is slow.

.github/dependabot.yml

@@ -0,0 +1,33 @@
+# Version updates are monthly and grouped into one PR per ecosystem.
+# Security updates are separate and run whenever an advisory is published.
+version: 2
+updates:
+- package-ecosystem: cargo
+  directory: /
+  target-branch: dev
+  schedule:
+    interval: monthly
+  open-pull-requests-limit: 5
+  groups:
+    all:
+      patterns:
+      - '*'
+  ignore:
+  - dependency-name: freemkv-unlock
+  - dependency-name: libfreemkv
+  - dependency-name: freemkv-keysources
+  - dependency-name: freemkv-i18n
+  - dependency-name: freemkv-engine
+- package-ecosystem: github-actions
+  directory: /
+  target-branch: dev
+  schedule:
+    interval: monthly
+  open-pull-requests-limit: 5
+  groups:
+    all:
+      patterns:
+      - '*'
+  ignore:
+  - dependency-name: dtolnay/rust-toolchain
+  - dependency-name: freemkv/.github*

.github/workflows/ci.yml

@@ -2,35 +2,261 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    # dev -> qa -> main. `dev` is where work lands and is meant to be pushed
+    # to often: these are the FAST checks, so a mistake surfaces in minutes.
+    # `qa` is the release candidate — it runs these too, plus the expensive
+    # suite in qa.yml. `main` only ever moves at release time, to a tagged
+    # commit that was already green on qa.
+    branches: [main, dev, qa]
   pull_request:
 
-# freemkv-keysources depends on libfreemkv from crates.io (see Cargo.toml).
-# No sibling-repo checkout is needed.
+# Rapid dev pushes supersede their own in-progress runs instead of stacking.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# WHY THE SIBLING CHECKOUTS — this is NOT a monorepo.
+#
+# The committed Cargo.toml resolves libfreemkv from a git TAG (it is off
+# crates.io). That means CI was building this branch against the LAST RELEASE
+# of libfreemkv, never against libfreemkv's dev tip — so a coordinated change
+# across the two repos could not be verified until release-orchestrate.yml cut the tags.
+# Green here meant "compiles against last month's library".
+#
+# The fix mirrors the developer's local layout via the shared composite
+# freemkv/.github//actions/checkout-siblings: every sibling repo is checked out
+# into a subdirectory of $GITHUB_WORKSPACE, reproducing
+# ~/Developer/freemkv/{freemkv-keysources,libfreemkv,freemkv-unlock}, and a
+# generated .cargo/config.toml redirects the git-tag patch to those paths.
+# Config-level [patch.crates-io] wins over the manifest one, which is the same
+# mechanism local development already uses (see the note in Cargo.toml).
+#
+# Subdirectories rather than `../libfreemkv` because actions/checkout refuses
+# any `path:` outside $GITHUB_WORKSPACE, and the workspace IS the repo dir.
+# Repos stay separate, tags stay separate, the release cascade is untouched.
+#
+# libfreemkv path-deps ../freemkv-unlock, which resolves to the workspace root
+# under this layout — hence the third checkout.
+#
+# `--locked` is deliberately absent: Cargo.lock is now committed (issue #15) and
+# the `deny` job audits the resolved graph, but CI's sibling path-patch layout
+# resolves the freemkv crates as path packages, which `--locked` can't satisfy —
+# the same reason the binary crates omit it. The lock that has to hold is the one
+# release-orchestrate.yml regenerates in each consuming binary.
 
 jobs:
-  lint:
+  # Single source of truth for the MSRV — read rust-version from Cargo.toml once
+  # and export it; MSRV-bound jobs consume needs.resolve-msrv.outputs.v. clippy
+  # runs on stable instead (see CI.md's Toolchain policy).
+  resolve-msrv:
+    runs-on: ubuntu-latest
+    outputs:
+      v: ${{ steps.msrv.outputs.v }}
+    steps:
+      - uses: actions/checkout@v7
+      - id: msrv
+        shell: bash
+        run: echo "v=$(grep -m1 '^rust-version' Cargo.toml | sed -E 's/.*\"([^\"]+)\".*/\1/')" >> "$GITHUB_OUTPUT"
+
+  # CI owns the changelog: main may never carry a released version without a
+  # CHANGELOG.md entry for it. The release orchestrator dates an existing
+  # `## [X.Y.Z]` heading — it does NOT invent one — so a version bump that
+  # forgot its changelog entry must fail here rather than ship a blank release.
+  # Hard-fails on main (and PRs targeting main); warns elsewhere so an
+  # in-progress dev/qa branch whose entry isn't written yet is not blocked.
+  changelog:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: dtolnay/rust-toolchain@1.86.0
+      - uses: actions/checkout@v7
+      - name: Require a CHANGELOG entry for the crate version on main
+        shell: bash
+        run: |
+          set -euo pipefail
+          version=$(grep -m1 '^version = ' Cargo.toml | sed -E 's/.*"([^"]+)".*/\1/')
+          if grep -qE "^## \[${version}\]" CHANGELOG.md; then
+            echo "CHANGELOG.md has an entry for ${version}."
+            exit 0
+          fi
+          msg="CHANGELOG.md has no '## [${version}]' entry"
+          if [ "${GITHUB_REF_NAME:-}" = "main" ] || [ "${GITHUB_BASE_REF:-}" = "main" ]; then
+            echo "::error::${msg} — main requires a changelog entry for the released version."
+            exit 1
+          fi
+          echo "::warning::${msg} (allowed on ${GITHUB_REF_NAME:-unknown}; required before it can reach main)."
+
+  lint:
+    needs: resolve-msrv
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
         with:
-          components: clippy, rustfmt
-      # Cache ~/.cargo/registry + target/ across runs. Saves ~30-60s
-      # of crates.io index download per job; incremental compilation
-      # helps on re-runs that don't bump Cargo.lock.
+          path: freemkv-keysources
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
+        with:
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv freemkv-unlock
+          self: freemkv-keysources
+      # fmt runs on the MSRV pin; clippy runs on stable so new-lint debt is a
+      # blocking gate the pinned toolchain would hide. Stable is installed first
+      # for clippy; the MSRV pin goes second so it stays fmt's default toolchain.
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
+          components: rustfmt
       - uses: Swatinem/rust-cache@v2
         with:
-          shared-key: freemkv-keysources-ci
+          workspaces: freemkv-keysources
       - run: cargo fmt --check
-      - run: cargo clippy -- -D warnings
+        working-directory: freemkv-keysources
+      # --all-targets so the test code is linted too, not just the library.
+      - run: cargo +stable clippy --all-targets -- -D warnings
+        working-directory: freemkv-keysources
 
   test:
+    needs: resolve-msrv
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: dtolnay/rust-toolchain@1.86.0
+      - uses: actions/checkout@v7
+        with:
+          path: freemkv-keysources
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
+        with:
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv freemkv-unlock
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
       - uses: Swatinem/rust-cache@v2
         with:
-          shared-key: freemkv-keysources-ci
-      - run: cargo test --locked
+          workspaces: freemkv-keysources
+      - run: cargo test --tests
+        working-directory: freemkv-keysources
+
+  # Dependency-audit gate. Mirrors the `test` job's sibling-checkout layout and
+  # generated .cargo/config.toml so `cargo metadata` resolves the git-tag patch
+  # to the local sibling paths; cargo-deny then audits advisories, bans,
+  # licenses, and sources against the committed deny.toml.
+  deny:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: freemkv-keysources
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
+        with:
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv freemkv-unlock
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: taiki-e/install-action@cargo-deny
+      # Run from the repo dir so the generated .cargo/config.toml path patches apply.
+      - run: cargo deny --all-features check advisories bans licenses sources
+        working-directory: freemkv-keysources
+
+  # This crate ships wherever freemkv and autorip ship, and it drags in all of
+  # libfreemkv's platform code (SCSI transports included). Build the tests, not
+  # `cargo check` — check skips codegen and never compiles test-only code.
+  check-macos:
+    # dev is the FAST lane: this job still runs, but on the release-candidate
+    # branches rather than on every push to dev. Nothing is deleted and no
+    # platform stops being checked before a release -- qa.yml independently
+    # covers macOS and Windows, and the jobs unique to this file (the Intel
+    # macOS build, the Windows release build) run here on qa and main. A push
+    # to dev is meant to be cheap and frequent; waiting on three runner pools
+    # to agree is what a release candidate is for.
+    #
+    # `if` SKIPS the job (it does not queue). A queued job would be far worse
+    # than a slow one: a never-scheduled job leaves the run pending forever, so
+    # the branch's required checks never report complete.
+    needs: resolve-msrv
+    if: github.ref_name == 'qa' || github.ref_name == 'main'
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: freemkv-keysources
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
+        with:
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv freemkv-unlock
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: freemkv-keysources
+      - run: cargo build --tests
+        working-directory: freemkv-keysources
+
+  # Additive, NON-REQUIRED coverage. Mirrors the `test` job's sibling-checkout
+  # layout and pinned toolchain (nothing in the release cascade depends on it,
+  # and codecov upload is tokenless with fail_ci_if_error:false, so a flaky
+  # upload never reddens the run). `--locked` is deliberately absent here for
+  # the same reason it is in `test`: CI's sibling path-patch layout resolves the
+  # freemkv crates as path packages, which `--locked` can't satisfy.
+  coverage:
+    needs: resolve-msrv
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: freemkv-keysources
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
+        with:
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv freemkv-unlock
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
+          components: llvm-tools-preview
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: freemkv-keysources
+      - uses: taiki-e/install-action@cargo-llvm-cov
+      - run: cargo llvm-cov --workspace --ignore-run-fail --lcov --output-path lcov.info
+        working-directory: freemkv-keysources
+      - uses: codecov/codecov-action@v7
+        with:
+          files: freemkv-keysources/lcov.info
+          slug: freemkv/freemkv-keysources
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  check-windows:
+    # dev is the FAST lane: this job still runs, but on the release-candidate
+    # branches rather than on every push to dev. Nothing is deleted and no
+    # platform stops being checked before a release -- qa.yml independently
+    # covers macOS and Windows, and the jobs unique to this file (the Intel
+    # macOS build, the Windows release build) run here on qa and main. A push
+    # to dev is meant to be cheap and frequent; waiting on three runner pools
+    # to agree is what a release candidate is for.
+    #
+    # `if` SKIPS the job (it does not queue). A queued job would be far worse
+    # than a slow one: a never-scheduled job leaves the run pending forever, so
+    # the branch's required checks never report complete.
+    needs: resolve-msrv
+    if: github.ref_name == 'qa' || github.ref_name == 'main'
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: freemkv-keysources
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
+        with:
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv freemkv-unlock
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: freemkv-keysources
+      - run: cargo build --tests
+        working-directory: freemkv-keysources

.github/workflows/comment-guard.yml

@@ -0,0 +1,12 @@
+name: comment-guard
+
+# Thin caller → the canonical reusable guard in freemkv/.github (one definition
+# for every repo). Fork PRs still run it; same-repo pushes aren't double-run.
+on: [push, pull_request]
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  comment-guard:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork
+    uses: freemkv/.github/.github/workflows/guard-comment.yml@v2

.github/workflows/identity-guard.yml

@@ -0,0 +1,14 @@
+name: identity-guard
+
+# Thin caller → the canonical reusable guard in freemkv/.github.
+on:
+  push:
+    branches: [dev, qa, main]
+  pull_request:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  identity:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork
+    uses: freemkv/.github/.github/workflows/guard-identity.yml@v1

.github/workflows/leak-guard.yml

@@ -1,35 +1,11 @@
 name: leak-guard
 
-# Self-contained public-repo leak gate. Public CI cannot reach the private
-# tooling, so this encodes only the generic net: internal-infra references,
-# tracked CLAUDE.md/.claude paths, and AI-attribution in commit messages.
-# No project-specific reverse-engineering vocabulary lives here.
-
+# Thin caller → the canonical reusable guard in freemkv/.github.
 on: [push, pull_request]
-
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 jobs:
   leak-guard:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
-      - name: Compute commit range
-        id: range
-        run: |
-          if [ "${{ github.event_name }}" = "pull_request" ]; then
-            base="${{ github.event.pull_request.base.sha }}"
-            head="${{ github.event.pull_request.head.sha }}"
-            echo "range=$base..$head" >> "$GITHUB_OUTPUT"
-          else
-            before="${{ github.event.before }}"
-            after="${{ github.sha }}"
-            # New branch / first push: github.event.before is all-zeros.
-            if [ -z "$before" ] || [ "$before" = "0000000000000000000000000000000000000000" ]; then
-              echo "range=$after" >> "$GITHUB_OUTPUT"
-            else
-              echo "range=$before..$after" >> "$GITHUB_OUTPUT"
-            fi
-          fi
-      - name: Run leak-guard
-        run: bash ci/leak-guard.sh "${{ steps.range.outputs.range }}"
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork
+    uses: freemkv/.github/.github/workflows/guard-leak.yml@v1

.github/workflows/qa.yml

@@ -0,0 +1,157 @@
+name: qa
+
+# ── The qa gate: "is this production worth?" ────────────────────────────────
+#
+# dev -> qa -> main.
+#
+# `dev` is for committing often. ci.yml answers "is it green" in minutes with
+# fmt, clippy and the unit suite, so a mistake surfaces while it is still cheap
+# to fix. `qa` is the release-candidate branch, and THIS workflow is the claim
+# that a commit is production worth: everything expensive that can run without
+# physical media. `main` only ever receives a qa that went green here.
+#
+# Sibling repos are checked out at `qa`, NOT `dev`. A qa run that resolved its
+# dependencies from dev tips would be validating a combination that is not the
+# one being released, which is the exact failure this branch exists to prevent.
+# The shared checkout-siblings composite resolves qa->qa from the caller branch.
+#
+# What this gate CANNOT cover: `disc://` and real `iso://` need physical media,
+# and no hosted runner has an optical drive or the image hoard. That coverage
+# lives in freemkv's qa.yml (the real-media EC2 matrix), not in this file.
+on:
+  push:
+    branches: [qa]
+  workflow_dispatch:
+
+# Supersede an in-progress qa run when a newer candidate lands on the branch.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Single source of truth for the MSRV — see ci.yml. Jobs that build/test AT
+  # the MSRV read needs.resolve-msrv.outputs.v from Cargo.toml's rust-version;
+  # clippy (cross-lint) runs on stable instead.
+  resolve-msrv:
+    runs-on: ubuntu-latest
+    outputs:
+      v: ${{ steps.msrv.outputs.v }}
+    steps:
+      - uses: actions/checkout@v7
+      - id: msrv
+        shell: bash
+        run: echo "v=$(grep -m1 '^rust-version' Cargo.toml | sed -E 's/.*\"([^\"]+)\".*/\1/')" >> "$GITHUB_OUTPUT"
+
+  # ── Name the candidate ────────────────────────────────────────────────
+  #
+  # Every push to `qa` is a release candidate, so every push gets a tag:
+  # v<version>-rc<N>, N incrementing. That is the answer to "which build is on
+  # qa right now, and is it the one I tested?" — a question that otherwise gets
+  # answered from memory.
+  #
+  # This runs FIRST and does not depend on the gates, deliberately. A red
+  # candidate needs a name more than a green one does: "rc3 failed
+  # release-tests on windows" is a sentence you can act on; "qa is red" is not.
+  # Red on qa is a working gate, not an incident — it is the branch saying this
+  # is not production worth yet. Fix on dev, get dev green, push qa again.
+  #
+  # release.yml excludes v*-rc* so a candidate never publishes a release.
+  rc-tag:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Stamp the next rc
+        shell: bash
+        run: |
+          set -euo pipefail
+          v=$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -1)
+          [ -n "$v" ] || { echo "no version in Cargo.toml" >&2; exit 1; }
+          # Numeric sort on the rc ordinal: -rc10 must beat -rc9, and a plain
+          # lexical sort gets that backwards from the tenth candidate on.
+          n=$(git tag -l "v$v-rc*" | sed "s|^v$v-rc||" | sort -n | tail -1)
+          tag="v$v-rc$(( ${n:-0} + 1 ))"
+          git tag "$tag"
+          git push origin "$tag"
+          echo "### Candidate \`$tag\`" >> "$GITHUB_STEP_SUMMARY"
+
+  # The debug suite runs on every dev push. Release is a DIFFERENT build:
+  # overflow checks are off, debug_assert! is compiled out, and inlining
+  # changes what the optimiser can prove. A test that only passes in debug is
+  # a test that never guarded the binary anyone actually ships.
+  release-tests:
+    needs: resolve-msrv
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ['ubuntu-latest', 'macos-latest']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: freemkv-keysources
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
+        with:
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv freemkv-unlock
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: freemkv-keysources
+      - run: cargo test --release --tests
+        working-directory: freemkv-keysources
+
+  # clippy's output is target-dependent: cfg-gated code only gets linted on
+  # the target it compiles for. Linting solely on the dev machine's host
+  # target is how a lint that CI rejects reaches a push.
+  cross-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: freemkv-keysources
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
+        with:
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv freemkv-unlock
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: freemkv-keysources
+      - run: rustup target add x86_64-unknown-linux-gnu
+      - run: cargo clippy --all-targets --target x86_64-unknown-linux-gnu -- -D warnings
+        working-directory: freemkv-keysources
+
+  # Windows compiles the tests but does not run them, matching the policy
+  # ci.yml already set. The value here is codegen: the #[cfg(windows)] halves
+  # of the SCSI transport and platform layers compile on no other runner, so
+  # without this they are first built at release time.
+  windows-build:
+    needs: resolve-msrv
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: freemkv-keysources
+      - uses: freemkv/.github/.github/actions/checkout-siblings@v1
+        with:
+          checkout: libfreemkv freemkv-unlock
+          patch: libfreemkv freemkv-unlock
+          self: freemkv-keysources
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ needs.resolve-msrv.outputs.v }}
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: freemkv-keysources
+      - run: cargo build --release --tests
+        working-directory: freemkv-keysources

.github/workflows/release.yml

@@ -4,6 +4,11 @@ on:
   push:
     tags:
       - 'v*'
+      # NOT the release-candidate tags. Every push to `qa` stamps a
+      # v<version>-rc<N> so a run can be named, and 'v*' matches those too —
+      # which would have this workflow build and PUBLISH a GitHub release for
+      # every candidate, including the red ones.
+      - '!v*-rc*'
 
 permissions:
   contents: write
@@ -12,7 +17,7 @@ jobs:
   verify:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
       - name: Verify Cargo.toml version matches tag
         run: |
           CARGO_VER="v$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')"
@@ -24,28 +29,32 @@ jobs:
 
   # Tests run as a PARALLEL TRIPWIRE: they fail the run if they fail, but the
   # release job does NOT `needs:` this job. The tag decision was already gated by
-  # the local precommit (same Rust 1.86, same commit).
+  # CI (ci.yml on dev, then a green qa.yml on the same commit).
   #
-  # freemkv-keysources is a library — Cargo.lock isn't tracked, so --locked
-  # would always fail (no lockfile to lock against on a fresh runner). Its
+  # Cargo.lock is now committed (issue #15), but --locked is still omitted: on
+  # the runner the libfreemkv dep resolves from crates.io, not the local path
+  # patch, which --locked can't reconcile. Its
   # libfreemkv dep resolves from crates.io (the dev .cargo/config.toml patch is
   # gitignored and absent on the runner), so libfreemkv must already be published
-  # at this version — the release script enforces that ordering before tagging.
+  # at this version — release-orchestrate.yml enforces that ordering before tagging.
   test:
     needs: verify
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: dtolnay/rust-toolchain@1.86.0
+      - uses: actions/checkout@v7
+      - id: msrv
+        shell: bash
+        run: echo "v=$(grep -m1 '^rust-version' Cargo.toml | sed -E 's/.*\"([^\"]+)\".*/\1/')" >> "$GITHUB_OUTPUT"
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ steps.msrv.outputs.v }}
       - uses: Swatinem/rust-cache@v2
       - run: cargo test
 
-  # NOTE: the crates.io publish is driven by the maintainer's release tooling
-  # from local credentials, not from CI — this repo has no CARGO_REGISTRY_TOKEN
-  # secret. release.sh runs `cargo publish --no-verify` locally. CI here only
-  # verifies the version/tag match, runs tests (tripwire), and cuts the GitHub
-  # Release. The binaries git-tag-pin keysources, so they don't wait on the
-  # crates.io publish — it serves external consumers in parallel.
+  # NOTE: there is no crates.io publish — keysources is `publish = false` and
+  # git-tag-only. Consumers git-tag-pin it via a committed [patch.crates-io], so
+  # the git tag itself is the release artifact. CI here only verifies the
+  # version/tag match, runs tests (tripwire), and cuts the GitHub Release.
 
   release:
     # Only needs `verify`; the GitHub Release is cut as soon as the version
@@ -53,8 +62,8 @@ jobs:
     needs: verify
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           generate_release_notes: true

.gitignore

@@ -1,5 +1,4 @@
 /target
-Cargo.lock
 
 # session scratch — never track (may contain RE breadcrumbs)
 scratch/

CHANGELOG.md

@@ -1,5 +1,323 @@
 # Changelog
 
+## [1.8.2] — Unreleased
+
+### Added
+
+- The online source logs its connection-slot wait and DNS time before each request.
+
+## [1.8.1] — 2026-10-07
+
+### Changed
+
+- Unit tests live in `*_tests.rs` side files. No behaviour change.
+
+## [1.8.0] — 2026-10-05
+
+### Fixed
+
+- The online key service ignores `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY`: with one set, every key lookup failed (the pinned resolver also answered the proxy's address, so the proxy request went to the key service).
+
+### Changed
+
+- `KeydbSource` hands out host certs best first, with no disc input: certs with no `Revoked in MKBv<N>` note in keydb order, then revoked ones by latest revocation. The inherent `host_certs()` and the `KeySource::host_certs` trait method both return this order; the trait ignores its `mkb` argument.
+
+### Deprecated
+
+- `KeyDb::host_certs(mkb)`: use `KeyDb::host_certs_ranked`.
+
+### Added
+
+- `KeyDb::host_certs_ranked`.
+- `check_keyserver_url` with `KeyserverUrlRejection`/`KeyserverUrlFault`: a typed Permanent vs Temporary verdict, so callers need not match `validate_keyserver_url`'s text.
+- `test-hooks` feature exposing `set_last_decode_reachability`, to test decode-verdict handling without a network.
+
+## [1.7.7] — 2026-09-26
+
+### Maintenance
+
+- Replace comment-overflow documentation with concise source contracts and README instructions; enforce the shared comment policy in CI.
+
+## [1.7.6] — 2026-09-26
+
+### Changed
+
+- Version aligned to 1.7.6 for the unified release. No functional changes to this crate; the release is driven by the freemkv 1.7.6 Linux desktop shell (GTK4 + libadwaita) and the rip-finished desktop notification (issue #56).
+
+## [1.7.5] — 2026-09-23
+
+### Changed
+
+- Version aligned to 1.7.5 for the unified release. No functional changes to this crate; the release is driven by freemkv-unlock mirroring the freemkv-firmware 0.9.0 ABI (the drive's `Ake` and `Bus` levers retired into a single `Encryption` lever).
+
+## [1.7.4] — 2026-09-21
+### Fixed
+
+- keydb lookups now report match state and entry shape, so a "no entry" result tells you whether the disc was truly absent or matched-but-underivable (no usable VID) (#46).
+- ureq 3.4.2 with a bounded, rolling-idle reply body, so a slow-but-progressing download is no longer killed by an absolute deadline.
+
+### Maintenance
+
+- CI moved to the central reusable workflows.
+
+## [1.7.3] — 2026-09-19
+
+### Changed
+
+- Unified release with freemkv 1.7.3 (`info --share` disc-structure capture for bug reports + the multi-angle UHD main-title fix in libfreemkv; see the libfreemkv/freemkv 1.7.3 notes). No functional changes to this crate.
+
+## [1.7.2] — UNRELEASED
+
+### Added
+
+- `OnlineSource` now records the reachability outcome of its actual `/decode` POST (an HTTP `Status(code)` for any answer, including 200/404/422/429/5xx, or `Transport` for a connect/timeout/DNS/TLS failure) in a per-thread slot, readable via the new `take_last_decode_reachability()` / `DecodeReachability`. This lets a caller (autorip) classify a no-key result from the REAL decode's outcome instead of firing a second, redundant probe against the POST-only endpoint. No behavioural change to key resolution itself.
+
+## [1.7.1] — UNRELEASED
+
+### Changed
+
+- Version aligned to 1.7.1 for the unified release (freemkv-unlock 1.7.1 LibreDrive unlock fix); no functional changes.
+
+## [1.7.0] — 2026-09-02
+
+### Changed
+
+- Version aligned to 1.7.0 for the unified release. Internal CI/lint hardening only (stable-clippy MSRV split, cargo-deny dependency-audit gate, audience-based comment-guard); no functional changes.
+
+## [1.6.14] — 2026-08-31
+
+### Changed
+
+- Version aligned to 1.6.14 for the unified release.
+
+## [1.6.13] — 2026-08-28
+
+### Changed
+
+- Version aligned to 1.6.13 for the unified release.
+
+## [1.6.12] — 2026-08-27
+
+### Changed
+
+- Version aligned to 1.6.12 for the unified release; no functional changes.
+
+## [1.6.11] — 2026-08-26
+
+### Changed
+
+- Version aligned to 1.6.11 for the unified release. No functional changes to
+  this crate; the release was driven by the libfreemkv main-feature selection
+  improvements and the autorip mux-quarantine fix (see the libfreemkv and
+  autorip 1.6.11 notes).
+
+### Added
+
+- Codecov coverage reporting and badge.
+- Substantially expanded unit-test coverage.
+
+## [1.6.10] — 2026-08-23
+
+### Changed
+
+- Version aligned to 1.6.10 for the unified release. No functional changes to
+  this crate; the release was driven by libfreemkv (TrueHD/MLP audio now resyncs
+  to the next major-sync access unit after a source transport-stream
+  discontinuity, instead of splicing post-gap audio mid-stream — fixing
+  decoder-choking seams on discs whose stream carries a continuity-counter gap;
+  see the libfreemkv 1.6.10 notes).
+
+## [1.6.9] — 2026-08-22
+
+### Changed
+
+- Version aligned to 1.6.9 for the unified release. No functional changes to
+  this crate; the release was driven by autorip (automatic per-episode TV
+  ripping — each episode named `S{NN}E{MM}`, with TMDB runtime-aligned episode
+  numbering across multi-disc seasons — a Manual Rename option, and a unified
+  per-disc staging state file — see the autorip 1.6.9 notes).
+
+## [1.6.8] — 2026-08-21
+
+### Changed
+
+- Version aligned to 1.6.8 for the unified release. No functional changes to
+  this crate; the release was driven by autorip (webhooks now fire per pipeline
+  stage — Rip / Mux / Move — with the Rip hook firing the moment the drive is
+  free again, plus a Ripper-tab activity-banner fix so it also shows during
+  moves — see the autorip 1.6.8 notes).
+
+## [1.6.7] — 2026-08-21
+
+### Changed
+
+- Version aligned to 1.6.7 for the unified release. No functional changes to
+  this crate; the release was driven by autorip (per-webhook event selection,
+  a progress bar per moved artifact, and move-queue / webhook-error fixes —
+  see the autorip 1.6.7 notes).
+
+## [1.6.6] — 2026-08-20
+
+### Changed
+
+- Version aligned to 1.6.6 for the unified release. No functional changes
+  to this crate; the release was driven by autorip (webhooks may now target
+  private/LAN addresses — see the autorip 1.6.6 notes).
+
+## [1.6.5] — 2026-08-20
+
+### Fixed
+
+- **A media, disc-ID, or VUK key at the end of a keydb row is no longer
+  lost to the comment beside it.** Many `keydb.cfg` rows end with a
+  `; MKBv…` note. When that note sat directly after the row's final
+  field and that field was the media key (`M`), disc ID (`I`), or VUK
+  (`V`) — rather than a unit key (`U`) — the note was read as part of the
+  value, the hex parse failed, and the key was silently dropped, so the
+  disc reported no key even though the file held one. The note is now
+  stripped from those three fields exactly as it already was from the
+  unit-key field (a hex value never contains `;`, so the split is safe).
+  A disc that stopped resolving for this reason resolves again.
+
+- **A misconfigured key service is no longer quieter than an outage.** A
+  mistyped port, an `http://` URL, or a key-service address the SSRF guard
+  refuses all mean the same thing: the service was never asked, so nothing is
+  known about the disc. They were reported as an empty result — the same value a
+  service returns when it genuinely holds no key — so a standing
+  misconfiguration surfaced to the operator as "no key for this disc" and never
+  self-corrected, while a transient DNS failure was correctly reported as a
+  failure. All three are now failures, logged at error level and separated in
+  the log text from an outage: one says fix the URL, the other says wait. A
+  later key source's real key still wins, so nothing that used to rip stops
+  ripping.
+- **A replaced `keydb.cfg` can no longer be missed.** The parsed keydb is cached
+  behind the file's identity, and that identity was size plus modification time
+  — which are byte-identical when a file is replaced within the same second by
+  one of the same length, the common shape of a daily refresh on a filesystem
+  that records whole seconds. The old, superseded keys were then served for the
+  rest of the process's life while every lookup reported success. The identity
+  now includes the file's inode, and a cache entry is not trusted until the file
+  has been unmodified long enough for its timestamp to be meaningful.
+- **A corrupt keydb keeps saying so.** The summary warning that counts rejected
+  and duplicated rows is produced while parsing, and the cache skips parsing —
+  so a damaged keydb warned once, at whatever moment it was first read, and was
+  then served in silence to every later disc. The summary is now re-emitted on
+  every lookup that serves that file. An intact keydb stays silent.
+- **A keydb's identity and its contents are read through one file handle.** The
+  cache used to stat the path and then separately open it, so a replacement
+  landing between the two stored one file's identity beside another file's keys.
+
+### Security
+
+- **`{:?}` on a keydb no longer spells out its keys.** `KeyDb` and
+  `DiscEntry` derived their `Debug`, so a single `{:?}` in a log line, a
+  tracing field, or a panic message wrote out every processing key and
+  every disc's media key, disc ID, VUK, and unit keys in full — on the
+  published file, all 184,860 discs' worth. Both are public API, so any
+  caller could trip it. Both types now format through a redacting `Debug`
+  that names each field without its bytes, matching the AACS types this
+  parser was split from, and a test fails if the plain derive ever returns.
+
+- **The host certificate's redaction is now pinned by a test.** `{:?}` on a
+  keydb host certificate does not print the AACS host private key, and never
+  did — but that depended entirely on libfreemkv's own redacting formatter,
+  with nothing in this crate to notice if it changed. The whole-database
+  formatter's test did not cover it. It does now, along with device keys.
+
+### Changed
+
+- **Breaking (API):** `KeyDb::disc_entries`' key and `DiscEntry::disc_hash` are
+  `Arc<str>` rather than `String` (a ~13 MB saving on the published keydb, which
+  is now held in memory). Code that requires an owned `String` from either needs
+  `.to_string()`. Unreleased in 1.6.4; recorded here because it shipped to git
+  consumers without a note.
+
+## [1.6.4] — 2026-08-15
+
+### Changed
+
+- **No functional change.** This crate ships alongside the rest of freemkv at a
+  matching version; its behaviour is untouched.
+
+## [1.6.3] — 2026-08-10
+
+### Changed
+
+- **The key service is reached over a newer HTTP client, with the same
+  protections.** Before contacting a key service this crate resolves the host,
+  rejects any private or link-local address, and then pins the connection to the
+  addresses it just checked, so a hostname cannot be re-pointed at an internal
+  machine in the moment between the check and the request. That behaviour is
+  unchanged; only the client underneath it moved.
+
+### Security
+
+- **The address pinning is now proven by a test rather than assumed.** The checks
+  that reject a bad address were well covered, but nothing verified that the
+  approved addresses were the ones actually connected to — and every existing
+  test still passed with that wiring removed entirely, because none of them
+  opened a connection. A connection made to an unreachable name can only
+  succeed if the pinned address is honoured, and that is now asserted. No
+  defect is being fixed here: the pinning was correct. It simply had no way of
+  telling anyone if it stopped being correct.
+
+## [1.6.2] — 2026-08-08
+
+Version sync with the workspace. No functional change in this crate.
+
+## [1.6.1] — 2026-08-07
+
+Version sync with the workspace. No functional change in this crate.
+
+## [1.6.0] — 2026-08-03
+
+### Fixed
+
+- **Key-service failures are no longer indistinguishable from "no key for this
+  disc".** `query` returned an empty vector for a 502, a 401, a 429, a
+  transport error and an unparseable body alike — the same value a successful
+  lookup with no match returns. It now returns a typed error, and the HTTP
+  status is classified into the operator action it implies: 401/403 the token,
+  429 back off, any other non-2xx the service. A genuine miss is a 200 with no
+  key, so every non-2xx is a failure by definition. A DNS failure or timeout
+  now counts as unreachable rather than as a bad URL.
+
+Version sync with the workspace (freemkv-engine split release). No source change
+in this crate; it remains a pluggable AACS key-source provider consumed by the
+`freemkv` CLI and libfreemkv's key resolver.
+
+## [1.5.2] — 2026-07-22
+
+Version sync with the workspace; inherits libfreemkv 1.5.2 (CSS DVD descramble
+fix). No source change in this crate.
+
+## [1.4.5] — 2026-07-18
+
+Version sync; inherits libfreemkv 1.4.5. `KeySource` split into `get_unit_keys` +
+`get_fmts_indexes`, and a keydb device-key parse bug on an uppercase `0X` hex
+prefix was fixed (case-insensitive hex parsing across the toolchain).
+
+## [1.4.4] — 2026-07-17
+
+Version sync; inherits libfreemkv 1.4.4. The online `/decode` request is built from
+a `DecodeSampleSet` proven sufficient by type rather than a runtime length check.
+
+## [1.4.3] — 2026-07-17
+
+Version sync; inherits libfreemkv 1.4.3. The online unit-key reply is parsed as a
+list (one key for an ordinary disc, the ordered set for a forensic-variant disc),
+and `MIN_SAMPLE_UNITS` is re-exported from libfreemkv.
+
+## [1.4.2] — 2026-07-15
+
+Version sync with the workspace; inherits libfreemkv 1.4.2. The keydb test that
+feeds real key material into the AACS crypto was adapted to the segregated
+`decrypt_unit` + `is_clean` primitives (behaviour unchanged).
+
+## [1.4.1] — 2026-07-14
+
+Version sync with the workspace; inherits libfreemkv 1.4.1.
+
 ## [1.4.0] — 2026-07-13
 
 Version sync with the workspace; inherits libfreemkv 1.4.0.

CODE_OF_CONDUCT.md

@@ -36,7 +36,7 @@ This Code of Conduct applies within all community spaces, and also applies when
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at owner@example.invalid. All complaints will be reviewed and investigated promptly and fairly.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported privately to the project maintainer via GitHub at https://github.com/MattJackson. All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the reporter of any incident.
 

CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing
+
+Thanks for your interest!
+
+- **Report a bug** — open an issue
+- **Fix a bug** — fork, branch, PR
+- **Suggest a feature** — open an issue first
+
+## Development
+
+```bash
+cargo build
+cargo test
+```
+
+## License
+
+MIT

Cargo.toml

@@ -1,10 +1,10 @@
 [package]
 name = "freemkv-keysources"
-version = "1.4.0"
+version = "1.8.1"
 edition = "2024"
-rust-version = "1.86"
+rust-version = "1.88"
 license = "MIT"
-description = "Pluggable AACS key sources (keydb, online key service) for libfreemkv. Each source looks a disc up and hands libfreemkv its terminal Unit Keys via get_uk; the library does all derivation."
+description = "Pluggable AACS key sources (keydb, online key service) for libfreemkv. Each source looks a disc up and hands libfreemkv its terminal Unit Keys via get_unit_keys; the library does all derivation."
 repository = "https://github.com/freemkv/freemkv-keysources"
 keywords = ["aacs", "blu-ray", "uhd", "decryption", "keydb"]
 categories = ["multimedia"]
@@ -17,27 +17,40 @@ publish = false
 # The crate provides the `KeySource` trait + `Key`/`DiscInputs` types these impls fill.
 # libfreemkv is git-only now; the committed [patch.crates-io] below redirects this
 # bare version req to the libfreemkv git tag (local dev overrides it to a path).
-libfreemkv = "1.4"
+libfreemkv = "1.8"
 # OnlineSource: POST disc inputs + samples to a key service over HTTP.
-ureq = { version = "2", features = ["json"] }
+ureq = { version = "3", features = ["json"] }
 serde_json = "1"
-base64 = "0.22"
+base64 = "0.23"
 # KeydbSource::save: decompress a downloaded keydb (.zip / .gz). Same versions
 # already in the resolved graph via libfreemkv — no new tree, no new HTTP stack.
 flate2 = "1"
-zip = { version = "2", default-features = false, features = ["deflate"] }
+zip = { version = "8", default-features = false, features = ["deflate"] }
 # Structural begin/end logging around the keyserver round-trip (never logs
 # key material).
 tracing = "0.1"
 
+[features]
+# `set_last_decode_reachability`, for consumers' tests only (enable in dev-dependencies).
+test-hooks = []
+
+[dev-dependencies]
+# `test_util` fixtures (`decrypt_unit`, …) for this crate's tests (keys-upfront
+# KU-P1). CI resolves it through the sibling path patch.
+libfreemkv = { version = "1.8", features = ["test-util"] }
+
 [profile.release]
 lto = "thin"
 codegen-units = 1
 
-# libfreemkv is git-only (off crates.io). Redirect the bare `libfreemkv = "1.2"`
+# libfreemkv is git-only (off crates.io). Redirect the bare `libfreemkv = "1.6"`
 # req above to the git tag — committed and CI-visible. The release script
 # rewrites this tag to the new version before regenerating Cargo.lock. Local dev
 # overrides it with a path patch via the gitignored .cargo/config.toml (a
 # config-level [patch.crates-io] wins over this manifest one for the same crate).
 [patch.crates-io]
-libfreemkv = { git = "https://github.com/freemkv/libfreemkv", tag = "v1.4.0" }
+libfreemkv = { git = "https://github.com/freemkv/libfreemkv", tag = "v1.8.1" }
+freemkv-unlock = { git = "https://github.com/freemkv/freemkv-unlock", tag = "v1.8.1" }
+
+[lints.clippy]
+uninlined_format_args = "allow"

README.md

@@ -0,0 +1,21 @@
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![CI](https://github.com/freemkv/freemkv-keysources/actions/workflows/ci.yml/badge.svg)](https://github.com/freemkv/freemkv-keysources/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/freemkv/freemkv-keysources/branch/dev/graph/badge.svg)](https://codecov.io/gh/freemkv/freemkv-keysources)
+
+# freemkv-keysources
+
+Pluggable AACS key sources (keydb, online key service) for
+[libfreemkv](https://github.com/freemkv/libfreemkv). Each source looks a disc up
+and hands libfreemkv its terminal Unit Keys via `get_unit_keys`; the library
+does all derivation.
+
+## Development
+
+Build API documentation with `cargo doc --no-deps --open` for source construction,
+keydb paths and online-query contracts. Run `cargo test --tests` to validate
+parsing, caching and request guards. Tests use synthetic keys and local fixtures;
+never commit real key material or credentials.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+| ------- | --------- |
+| 1.6.x   | Yes       |
+| < 1.6   | No        |
+
+Only the current 1.6.x line receives security fixes.
+
+## Reporting a vulnerability
+
+Report vulnerabilities privately through GitHub Security Advisories:
+https://github.com/freemkv/freemkv-keysources/security/advisories/new
+
+Do not open a public issue for a security report. Include the affected
+version, steps to reproduce, and the impact you believe the issue has.
+
+## Response time
+
+You will get an initial response within 7 days.

ci/leak-guard.sh

@@ -1,120 +0,0 @@
-#!/usr/bin/env bash
-#
-# leak-guard.sh — self-contained public-repo leak gate.
-#
-# This is the LAST line of defense in CI. It is intentionally self-contained:
-# public CI cannot reach the private tooling, so this script encodes ONLY the
-# generic net — internal infrastructure references, agent-context files, and
-# AI-attribution in commit messages. It deliberately contains NO project-
-# specific reverse-engineering vocabulary (those words would themselves be a
-# leak). The richer private scanner stays private.
-#
-# Fails (exit 1) if any of the following appear in the repo:
-#   1. a tracked CLAUDE.md or .claude/ path (agent context — never public),
-#   2. tracked file content matching the internal-infra net,
-#   3. a commit message (in the given range) with AI attribution.
-#
-# Usage:
-#   leak-guard.sh [<commit-range>]
-#     <commit-range>  optional git rev-list range to scan commit messages
-#                     (e.g. "abc..def"). If omitted, commit-message scan is
-#                     skipped (path + content checks always run).
-
-set -euo pipefail
-
-# Absolute path to this script, resolved before any cd, so we can exclude it
-# from the content scan (it necessarily contains the detection patterns).
-SELF_ABS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/$(basename "${BASH_SOURCE[0]}")"
-
-REPO="$(git rev-parse --show-toplevel)"
-cd "$REPO"
-
-fail=0
-note() { printf '  ✗ %s\n' "$1"; fail=1; }
-
-# Internal-infra net — GENERIC ONLY. This script ships in the public repo, so
-# the patterns themselves must not name any org-specific identifier (doing so
-# would itself leak the infra they guard). We catch the leak *class*:
-#   - RFC1918 private IPv4 ranges (10/8, 172.16/12, 192.168/16),
-#   - private/internal/non-routable TLDs (.internal/.local/.lan/.corp/.invalid),
-#   - docker.internal.
-# The full org-specific net (literal hostnames, service names, repo paths,
-# vendor tooling, …) lives ONLY in the private scanner and never ships here.
-INFRA_RE='\b10\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}|\b172\.(1[6-9]|2[0-9]|3[01])\.[0-9]{1,3}\.[0-9]{1,3}|\b192\.168\.[0-9]{1,3}\.[0-9]{1,3}|\.internal\b|\.local\b|\.lan\b|\.corp\b|\.invalid\b|docker\.internal'
-# Home-path net — GENERIC ONLY. Catches an absolute developer home path
-# committed into a tracked file (a macOS /Users/<user>/… or Linux /home/<user>/…
-# path). This names NO specific user — it matches the leak *class* (any home
-# path), so the pattern itself reveals nothing org- or person-specific. A real
-# leak (e.g. /Users/alice/Developer/x slipping into a public RELEASE.md) trips
-# this regardless of whose machine it came from. The username segment is a
-# literal-username class ([A-Za-z0-9._-]) so dynamic/templated paths that build
-# the user at runtime — shell `/home/$USER/`, doc `/home/<rip>/`, Rust
-# `/home/{user}/` — do NOT false-positive; only a baked-in literal home leaks.
-HOMEPATH_RE='/Users/[A-Za-z0-9._-]+/|/home/[A-Za-z0-9._-]+/'
-# AI-attribution net (case-insensitive). "claude" matches only as a standalone
-# word — NOT preceded by a dot/slash/alnum and NOT followed by .md — so legit
-# mentions of CLAUDE.md / .claude/ in a commit message don't false-positive.
-ATTR_RE='co-authored-by|generated with|🤖|(?<![.\/A-Za-z0-9])claude(?!\.md)'
-
-echo "── leak-guard: tracked agent-context paths ──"
-while IFS= read -r f; do
-  case "$f" in
-    CLAUDE.md|*/CLAUDE.md|.claude|.claude/*|*/.claude|*/.claude/*)
-      note "tracked agent-context file: $f (CLAUDE.md/.claude must never be tracked in a public repo)" ;;
-  esac
-done < <(git ls-files)
-
-# Match a PCRE against a file, emitting "LINE: MATCH". The pattern is passed as
-# an argument (not interpolated into a //) so metacharacters like the "/" in a
-# path-style token can't break the regex. Reads raw bytes so non-UTF-8 blobs
-# don't abort the scan.
-pcre_matches() {
-  perl -e '
-    my ($file, $re) = @ARGV;
-    open(my $fh, "<:raw", $file) or exit 0;
-    my $rx; eval { $rx = qr/$re/i }; exit 0 if $@;
-    while (my $l = <$fh>) { if ($l =~ /$rx/) { print "$.: $&\n"; } }
-  ' "$1" "$2" 2>/dev/null
-}
-
-# This script's own source necessarily contains the detection patterns (e.g.
-# the regex tokens in INFRA_RE), so scanning it would always self-flag. Skip it.
-SELF="$(git ls-files --full-name -- "$SELF_ABS" 2>/dev/null | head -1)"
-
-echo "── leak-guard: internal-infra references in tracked files ──"
-while IFS= read -r f; do
-  case "$f" in *.png|*.jpg|*.jpeg|*.ico|*.gif|*.bin|*.crate|*.gz|*.zip|*.pdf) continue ;; esac
-  [ -n "$SELF" ] && [ "$f" = "$SELF" ] && continue
-  [ -f "$f" ] || continue
-  while IFS= read -r hit; do
-    [ -z "$hit" ] && continue
-    note "internal-infra reference: $f:$hit"
-  done < <(pcre_matches "$f" "$INFRA_RE")
-  while IFS= read -r hit; do
-    [ -z "$hit" ] && continue
-    note "[HOME-PATH] absolute home path: $f:$hit (no local home path may be committed to a public repo)"
-  done < <(pcre_matches "$f" "$HOMEPATH_RE")
-done < <(git ls-files)
-
-RANGE="${1:-}"
-if [ -n "$RANGE" ]; then
-  echo "── leak-guard: AI-attribution in commit messages ($RANGE) ──"
-  while IFS= read -r sha; do
-    [ -z "$sha" ] && continue
-    msg="$(git log -1 --format='%B' "$sha" 2>/dev/null || true)"
-    # Pass the pattern as an argument (not interpolated into a //) so the
-    # lookbehind char class and "/" don't break the regex.
-    hit="$(printf '%s' "$msg" | perl -e '
-      my $re = $ARGV[0]; my $rx = qr/$re/i;
-      while (my $l = <STDIN>) { if ($l =~ /($rx)/) { print "$1\n"; last; } }
-    ' "$ATTR_RE" | head -1 || true)"
-    [ -n "$hit" ] && note "commit ${sha:0:12}: message contains \"$hit\" (owner rule: zero AI attribution, ever)"
-  done < <(git rev-list "$RANGE" 2>/dev/null || true)
-fi
-
-echo
-if [ "$fail" -ne 0 ]; then
-  echo "✗ leak-guard: blocking finding(s) above — DO NOT MERGE/PUBLISH"
-  exit 1
-fi
-echo "✓ leak-guard: clean"

codecov.yml

@@ -0,0 +1,19 @@
+# Coverage is informational only: it never blocks a merge or a release. The
+# release cascade is gated by ci.yml / qa.yml and the local precommit, not by
+# a coverage threshold.
+coverage:
+  status:
+    project:
+      default:
+        informational: true
+    patch:
+      default:
+        informational: true
+
+# No PR comment noise; the badge and the Codecov UI are enough.
+comment: false
+
+# Exclude non-product code from the coverage denominator.
+ignore:
+  - "tests/**"
+  - "ci/**"

deny.toml

@@ -0,0 +1,42 @@
+# cargo-deny — gates the RESOLVED dependency graph (issue #15).
+# Runs in CI against the committed Cargo.lock: RUSTSEC advisories, a permissive
+# licence allow-list, and source/ban hygiene. Update the lock (cargo update)
+# to clear an advisory rather than adding an `ignore` entry without cause.
+
+[advisories]
+yanked = "deny"
+# ignore = ["RUSTSEC-0000-0000"]  # only with a written justification
+
+[licenses]
+# The whole tree is permissive. r-efi's LGPL arm is satisfied by Apache-2.0
+# (its expression is "Apache-2.0 OR LGPL-2.1-or-later"), so no copyleft is
+# allowed here. Add a licence only when a real dependency introduces it.
+allow = [
+    "MIT",
+    "Apache-2.0",
+    "Apache-2.0 WITH LLVM-exception",
+    "0BSD",
+    "Unicode-3.0",
+    "Unlicense",
+    "Zlib",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "ISC",
+    "CDLA-Permissive-2.0",
+]
+confidence-threshold = 0.9
+
+[bans]
+multiple-versions = "warn"   # transitive dupes (digest 0.10/0.11 etc.) are noise, not a gate
+wildcards = "deny"
+# The freemkv siblings resolve as path deps under CI's path-patch layout, which
+# reads as a wildcard version req. That is internal, not a supply-chain wildcard.
+allow-wildcard-paths = true
+
+[sources]
+unknown-registry = "deny"
+unknown-git = "deny"
+# The freemkv siblings are first-party git-tag deps; allow git sources from
+# our own org only (CI resolves them as git, not the local path override).
+[sources.allow-org]
+github = ["freemkv"]

src/lib.rs

@@ -1,24 +1,10 @@
 //! Pluggable AACS key sources for libfreemkv.
 //!
-//! libfreemkv owns the AACS crypto; this crate provides the published
-//! [`KeySource`] implementations that look a disc up and drive the boil-down
-//! primitives down to terminal Unit Keys:
-//!
-//! - [`KeydbSource`] — a local `keydb.cfg` (source #1).
-//! - [`OnlineSource`] — a remote key service (source #2).
-//!
-//! Applications (autorip, the `freemkv` CLI) choose and order the sources from
-//! their own config — the local-vs-online policy is just which impls they plug
-//! in — then resolve and hand the resulting key to `Disc::decrypt_with`.
-//!
-//! Each source resolves a disc's terminal **Unit Keys** in one shot via
-//! [`KeySource::get_uk`], driving libfreemkv's boil-down crypto primitives for
-//! whatever level of material it holds. Compose several with [`MultiSource`] in
-//! the caller's chosen order. Reading the encrypted content-sample units a key
-//! server validates on, and applying the resolved keys against a disc, is
-//! decryption *mechanism* — it lives in the library
-//! (`libfreemkv::resolve_and_apply`, `libfreemkv::read_encrypted_units`), not
-//! here.
+//! libfreemkv owns the AACS crypto; this crate provides [`KeySource`] impls that look a disc up
+//! and drive the boil-down primitives to terminal Unit Keys: [`KeydbSource`] (local
+//! `keydb.cfg`) and [`OnlineSource`] (remote key service). Applications choose and order
+//! sources, then resolve and hand the key to `Disc::decrypt_with`; compose several with
+//! [`MultiSource`].
 
 mod keydb;
 /// The `keydb.cfg` parser (`KeyDb`, `DiscEntry`, …). Public: parsing the keydb
@@ -30,7 +16,13 @@ mod paths;
 
 pub use keydb::{KeydbSource, UpdateResult};
 pub use keydb_format::{DiscEntry, KeyDb};
-pub use online::{OnlineSource, validate_keyserver_url};
+#[cfg(feature = "test-hooks")]
+pub use online::set_last_decode_reachability;
+pub use online::{
+    DecodeReachability, KeyserverUrlFault, KeyserverUrlRejection, MIN_SAMPLE_UNITS, OnlineSource,
+    check_keyserver_url, check_keyserver_url_static, take_last_decode_reachability,
+    validate_keyserver_url,
+};
 pub use paths::{default_keydb_path, existing_keydb_path, keydb_search_paths};
 
 // Re-exported for downstream convenience so apps need only depend on this crate
@@ -39,10 +31,9 @@ pub use libfreemkv::aacs::types::UnitKey;
 pub use libfreemkv::keysource::ResolveCtx;
 pub use libfreemkv::{DiscInputs, KeySource};
 
-/// VUK → the disc's terminal Unit Keys (positional index), one AES-ECB-decrypt
-/// per encrypted title key. Composes the raw `aacs::derive::decrypt_unit_key`
-/// primitive directly — replaces the removed libfreemkv `aacs::boil::uk_from_vuk`
-/// wrapper (that veneer is gone; libfreemkv owns only the AES).
+// VUK -> the disc's terminal Unit Keys (positional index), one AES-ECB-decrypt
+// per encrypted title key, via `aacs::derive::decrypt_unit_key`. Replaces the
+// removed libfreemkv `aacs::boil::uk_from_vuk` wrapper.
 pub(crate) fn uks_from_vuk(vuk: &[u8; 16], enc_title_keys: &[[u8; 16]]) -> Vec<UnitKey> {
     enc_title_keys
         .iter()
@@ -51,13 +42,13 @@ pub(crate) fn uks_from_vuk(vuk: &[u8; 16], enc_title_keys: &[[u8; 16]]) -> Vec<U
         .collect()
 }
 
-/// An ordered composition of key sources, driven as one. [`MultiSource::get_uk`]
-/// tries each inner source in order and returns the first non-empty Unit Key
-/// set. **The caller supplies the list AND the order** — local-first `[Keydb,
-/// Online]`, online-first `[Online, Keydb]`, etc. —
-/// so the "which sources, in what order" policy lives entirely with the
-/// application, not the library. `MultiSource` is itself a [`KeySource`], so it
-/// nests and composes.
+/// An ordered composition of key sources, driven as one.
+///
+/// [`MultiSource::get_unit_keys`] tries each inner source in order and returns the first
+/// non-empty Unit Key set (and [`MultiSource::get_fmts_indexes`] does the same for the forensic
+/// set). The caller supplies the list AND the order — local-first `[Keydb, Online]`,
+/// online-first `[Online, Keydb]`, etc. `MultiSource` is itself a [`KeySource`], so it nests
+/// and composes.
 pub struct MultiSource {
     sources: Vec<Box<dyn KeySource>>,
 }
@@ -69,25 +60,86 @@ impl MultiSource {
     }
 }
 
-impl KeySource for MultiSource {
-    /// Try each inner source in order; the FIRST to return a non-empty Unit Key
-    /// set wins. An inner source that returns empty OR errors is treated as "no
-    /// key here" and the next is tried (a single source failure never blocks the
-    /// chain). All sources exhausted → empty.
-    fn get_uk(&self, ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
-        for s in &self.sources {
-            if let Ok(uks) = s.get_uk(ctx) {
-                if !uks.is_empty() {
-                    return Ok(uks);
+// Drive `sources` in order, returning the first non-empty result and preserving Ok/Err when
+// nothing resolves. `get` selects the trait method so the base and forensic paths share one
+// implementation.
+fn first_non_empty(
+    sources: &[Box<dyn KeySource>],
+    get: impl Fn(&dyn KeySource, &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error>,
+    ctx: &dyn ResolveCtx,
+) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+    let mut first_failure: Option<libfreemkv::Error> = None;
+    for s in sources {
+        match get(s.as_ref(), ctx) {
+            Ok(uks) if !uks.is_empty() => return Ok(uks),
+            Ok(_) => {}
+            Err(e) => {
+                if first_failure.is_none() {
+                    first_failure = Some(e);
                 }
             }
         }
-        Ok(Vec::new())
+    }
+    match first_failure {
+        // At least one source could not answer, and nothing else had a key: the
+        // composition does NOT know that this disc has no key.
+        Some(e) => Err(e),
+        // Every source answered; none holds a key. The genuine miss.
+        None => Ok(Vec::new()),
+    }
 }
 
-    /// UNION every inner source's host certs (filtered at the given MKB
-    /// generation). Without this a composed source would hide an inner source's
-    /// cert from the OEM cert-auth route — the gap this fixes.
+impl KeySource for MultiSource {
+    // First inner source to return a non-empty base Unit Key set wins. All
+    // exhausted -> `Ok(empty)` if all answered, else the first failure (see
+    // [`MultiSource`]).
+    fn get_unit_keys(&self, ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+        first_non_empty(&self.sources, |s, c| s.get_unit_keys(c), ctx)
+    }
+
+    // De-conflated counterpart: first inner source with keys wins; else the
+    // richest miss survives composition (a MATCHED inner source beats a plain
+    // miss). Same Err/Ok failure contract as `get_unit_keys`.
+    fn resolve_unit_keys(
+        &self,
+        ctx: &dyn ResolveCtx,
+    ) -> Result<libfreemkv::keysource::UnitKeyResolution, libfreemkv::Error> {
+        let mut first_failure: Option<libfreemkv::Error> = None;
+        let mut matched: Option<libfreemkv::keysource::UnitKeyResolution> = None;
+        for s in &self.sources {
+            match s.resolve_unit_keys(ctx) {
+                Ok(r) if !r.keys.is_empty() => return Ok(r),
+                Ok(r) => {
+                    if r.matched && matched.is_none() {
+                        matched = Some(r);
+                    }
+                }
+                Err(e) => {
+                    if first_failure.is_none() {
+                        first_failure = Some(e);
+                    }
+                }
+            }
+        }
+        if let Some(r) = matched {
+            return Ok(r);
+        }
+        match first_failure {
+            Some(e) => Err(e),
+            None => Ok(libfreemkv::keysource::UnitKeyResolution::default()),
+        }
+    }
+
+    // Forensic-index counterpart to `get_unit_keys`, same failure-preserving
+    // rule. A source with no forensic material (keydb, via the trait default)
+    // contributes empty and is skipped; today the online source answers.
+    fn get_fmts_indexes(&self, ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+        first_non_empty(&self.sources, |s, c| s.get_fmts_indexes(c), ctx)
+    }
+
+    /// UNION every inner source's host certs, in source order (`mkb` is passed
+    /// through unchanged). Without this a composed source would hide an inner
+    /// source's cert from the OEM cert-auth route — the gap this fixes.
     fn host_certs(&self, mkb: Option<u32>) -> Vec<libfreemkv::aacs::types::HostCert> {
         self.sources
             .iter()
@@ -98,4 +150,25 @@ impl KeySource for MultiSource {
     fn label(&self) -> &'static str {
         "multi"
     }
+
+    // KU3-6: depends on samples if ANY inner source does, so a nested
+    // sample-dependent source keeps getting the per-piece ask.
+    fn answer_depends_on_samples(&self) -> bool {
+        self.sources.iter().any(|s| s.answer_depends_on_samples())
     }
+
+    // Same `any(inner)` rule (KU-K1 review): `resolve` retries the composition
+    // whenever any inner source's last failure was transport-class.
+    fn last_failure_was_transport(&self) -> bool {
+        self.sources.iter().any(|s| s.last_failure_was_transport())
+    }
+
+    // KU J23: any inner source that consumes the VID makes the composition one.
+    fn uses_vid(&self) -> bool {
+        self.sources.iter().any(|s| s.uses_vid())
+    }
+}
+
+#[cfg(test)]
+#[path = "lib_tests.rs"]
+mod tests;

src/lib_tests.rs

@@ -0,0 +1,172 @@
+use super::*;
+use libfreemkv::aacs::types::HostCert;
+
+// A minimal KeySource that only supplies host certs — the sole MultiSource
+// behaviour under test. It never resolves a unit key.
+struct CertOnly {
+    certs: Vec<HostCert>,
+}
+impl KeySource for CertOnly {
+    fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+        Ok(Vec::new())
+    }
+    fn host_certs(&self, _mkb: Option<u32>) -> Vec<HostCert> {
+        self.certs.clone()
+    }
+}
+
+// A host cert tagged with a distinct marker byte so a returned set can be
+// identified exactly. Synthetic bytes only; no real key material.
+fn cert(marker: u8) -> HostCert {
+    HostCert {
+        private_key: [marker; 20],
+        certificate: vec![marker; 92],
+        private_key_v2: None,
+        certificate_v2: None,
+    }
+}
+
+fn boxed(certs: Vec<HostCert>) -> Box<dyn KeySource> {
+    Box::new(CertOnly { certs }) as Box<dyn KeySource>
+}
+
+/// `MultiSource::host_certs` must UNION every inner source's certs. Without
+/// this a composed source hides an inner source's cert from the OEM
+/// cert-auth route — the gap the union closes.
+#[test]
+fn multi_source_host_certs_unions_every_inner_source() {
+    let multi = MultiSource::new(vec![
+        boxed(vec![cert(0x01)]),
+        boxed(vec![cert(0x02), cert(0x03)]),
+    ]);
+    let mut markers: Vec<u8> = multi
+        .host_certs(Some(50))
+        .iter()
+        .map(|c| c.certificate[0])
+        .collect();
+    markers.sort_unstable();
+    assert_eq!(
+        markers,
+        vec![0x01, 0x02, 0x03],
+        "certs from every inner source must be unioned"
+    );
+}
+
+/// With no inner source holding a cert, the union is empty (not an error).
+#[test]
+fn multi_source_host_certs_empty_when_no_source_has_one() {
+    let multi = MultiSource::new(vec![boxed(vec![]), boxed(vec![])]);
+    assert!(multi.host_certs(None).is_empty());
+}
+
+// A source whose `answer_depends_on_samples` is fixed to the given value —
+// the only behaviour KSK2 exercises.
+struct FixedDependency(bool);
+impl KeySource for FixedDependency {
+    fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+        Ok(Vec::new())
+    }
+    fn answer_depends_on_samples(&self) -> bool {
+        self.0
+    }
+}
+
+// KSK2: `MultiSource::answer_depends_on_samples` is `any(inner)`, so nesting
+// a sample-dependent online source under a sample-independent keydb still
+// gets the per-piece ask (`resolve` must not treat the pair as keydb-only).
+#[test]
+fn multi_source_answer_depends_on_samples_is_any_inner() {
+    let all_independent = MultiSource::new(vec![
+        Box::new(FixedDependency(false)) as Box<dyn KeySource>,
+        Box::new(FixedDependency(false)) as Box<dyn KeySource>,
+    ]);
+    assert!(!all_independent.answer_depends_on_samples());
+
+    let keydb_then_online = MultiSource::new(vec![
+        Box::new(FixedDependency(false)) as Box<dyn KeySource>,
+        Box::new(FixedDependency(true)) as Box<dyn KeySource>,
+    ]);
+    assert!(keydb_then_online.answer_depends_on_samples());
+}
+
+// A source whose `uses_vid` is fixed to the given value.
+struct FixedVid(bool);
+impl KeySource for FixedVid {
+    fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+        Ok(Vec::new())
+    }
+    fn uses_vid(&self) -> bool {
+        self.0
+    }
+}
+
+// KU J23: like `answer_depends_on_samples`, a composed source uses the VID if any
+// inner one does, so a nested online source still makes a Missing piece VID-derivable.
+#[test]
+fn multi_source_uses_vid_is_any_inner() {
+    let neither = MultiSource::new(vec![
+        Box::new(FixedVid(false)) as Box<dyn KeySource>,
+        Box::new(FixedVid(false)) as Box<dyn KeySource>,
+    ]);
+    assert!(!neither.uses_vid());
+    let keydb_then_online = MultiSource::new(vec![
+        Box::new(FixedVid(false)) as Box<dyn KeySource>,
+        Box::new(FixedVid(true)) as Box<dyn KeySource>,
+    ]);
+    assert!(keydb_then_online.uses_vid());
+}
+
+// A source whose `last_failure_was_transport` is fixed to the given value.
+struct FixedTransport(bool);
+impl KeySource for FixedTransport {
+    fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+        Ok(Vec::new())
+    }
+    fn last_failure_was_transport(&self) -> bool {
+        self.0
+    }
+}
+
+// For consistency with `answer_depends_on_samples` (KU3-6): a composed
+// source's last-failure verdict is `any(inner)` too, so `resolve` retries
+// the composition whenever ANY inner source's last failure was transport.
+#[test]
+fn multi_source_last_failure_was_transport_is_any_inner() {
+    let none_transport = MultiSource::new(vec![
+        Box::new(FixedTransport(false)) as Box<dyn KeySource>,
+        Box::new(FixedTransport(false)) as Box<dyn KeySource>,
+    ]);
+    assert!(!none_transport.last_failure_was_transport());
+
+    let one_transport = MultiSource::new(vec![
+        Box::new(FixedTransport(false)) as Box<dyn KeySource>,
+        Box::new(FixedTransport(true)) as Box<dyn KeySource>,
+    ]);
+    assert!(one_transport.last_failure_was_transport());
+}
+
+/// The `mkb` generation must reach each inner source so its OWN revocation
+/// filter can act; a source that drops everything at a given generation is
+/// honoured by the union.
+#[test]
+fn multi_source_host_certs_passes_mkb_through_to_inner_sources() {
+    struct GenAware;
+    impl KeySource for GenAware {
+        fn get_unit_keys(&self, _c: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+            Ok(Vec::new())
+        }
+        fn host_certs(&self, mkb: Option<u32>) -> Vec<HostCert> {
+            match mkb {
+                // Modelled on a cert revoked in MKBv72.
+                Some(g) if g >= 72 => Vec::new(),
+                _ => vec![cert(0xaa)],
+            }
+        }
+    }
+    let multi = MultiSource::new(vec![Box::new(GenAware) as Box<dyn KeySource>]);
+    assert_eq!(multi.host_certs(Some(50)).len(), 1, "usable below gen 72");
+    assert!(
+        multi.host_certs(Some(72)).is_empty(),
+        "the gen must reach the inner source's filter"
+    );
+}

src/paths.rs

@@ -1,16 +1,11 @@
 //! Where the `keydb.cfg` lives: local to the executable, local ONLY.
 //!
-//! Key-path policy belongs with the key sources (this crate), not the library:
-//! libfreemkv is handed a path and reads it. The CLI/app asks here for the
-//! list of locations to *search* (first existing wins) and for the single
-//! *default* location to write to (e.g. `update-keys`/save).
+//! Key-path policy belongs here (key sources), not in libfreemkv, which
+//! just reads a handed-in path. This module gives the *search* list (first
+//! existing wins) and the single *default* write location.
 //!
-//! freemkv is a portable, standalone binary: the `keydb.cfg` lives *next to*
-//! the executable — `<dir of current exe>/keydb.cfg` — and nowhere else. There
-//! is no OS-specific config-dir lookup (`%APPDATA%`, `%USERPROFILE%\.config`,
-//! `$XDG_CONFIG_HOME`, `$HOME/.config`). Drop the exe and its `keydb.cfg` in
-//! the same folder and it works. Callers needing a custom location pass
-//! `--keydb PATH`, which bypasses this module entirely.
+//! freemkv is portable: `keydb.cfg` lives next to the exe — `<dir of current exe>/keydb.cfg` —
+//! with no OS config-dir fallback. `--keydb PATH` bypasses this module.
 
 use std::path::PathBuf;
 
@@ -51,45 +46,5 @@ pub fn default_keydb_path() -> Option<PathBuf> {
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-
-    /// The expected exe-local keydb path, computed the same way the code does.
-    /// Under `cargo test`, `current_exe()` is the test binary under `target/…`.
-    fn expected_local() -> Option<PathBuf> {
-        std::env::current_exe()
-            .ok()
-            .and_then(|exe| exe.parent().map(|dir| dir.join("keydb.cfg")))
-    }
-
-    #[test]
-    fn search_paths_is_exactly_exe_local_keydb() {
-        let paths = keydb_search_paths();
-        match expected_local() {
-            Some(expected) => {
-                assert_eq!(
-                    paths,
-                    vec![expected],
-                    "search list must be exactly [<exe dir>/keydb.cfg]"
-                );
-            }
-            None => {
-                // No exe dir available → empty, no OS fallback (local only).
-                assert!(
-                    paths.is_empty(),
-                    "no exe dir means an empty search list, never an OS fallback"
-                );
-            }
-        }
-    }
-
-    #[test]
-    fn default_path_matches_search_head() {
-        // The write default is the single search entry, or None if unavailable.
-        assert_eq!(default_keydb_path(), expected_local());
-        assert_eq!(
-            default_keydb_path(),
-            keydb_search_paths().into_iter().next()
-        );
-    }
-}
+#[path = "paths_tests.rs"]
+mod tests;

src/paths_tests.rs

@@ -0,0 +1,40 @@
+use super::*;
+
+/// The expected exe-local keydb path, computed the same way the code does.
+/// Under `cargo test`, `current_exe()` is the test binary under `target/…`.
+fn expected_local() -> Option<PathBuf> {
+    std::env::current_exe()
+        .ok()
+        .and_then(|exe| exe.parent().map(|dir| dir.join("keydb.cfg")))
+}
+
+#[test]
+fn search_paths_is_exactly_exe_local_keydb() {
+    let paths = keydb_search_paths();
+    match expected_local() {
+        Some(expected) => {
+            assert_eq!(
+                paths,
+                vec![expected],
+                "search list must be exactly [<exe dir>/keydb.cfg]"
+            );
+        }
+        None => {
+            // No exe dir available → empty, no OS fallback (local only).
+            assert!(
+                paths.is_empty(),
+                "no exe dir means an empty search list, never an OS fallback"
+            );
+        }
+    }
+}
+
+#[test]
+fn default_path_matches_search_head() {
+    // The write default is the single search entry, or None if unavailable.
+    assert_eq!(default_keydb_path(), expected_local());
+    assert_eq!(
+        default_keydb_path(),
+        keydb_search_paths().into_iter().next()
+    );
+}

tests/key_sources.rs

@@ -1,15 +1,12 @@
 //! Fixture-based integration tests for the published key sources.
 //!
 //! These exercise the *public* surface of `freemkv-keysources` end-to-end —
-//! real files on disk, the real `KeyDb`/`Mapfile` parsers from libfreemkv, and
-//! the `KeySource` trait (`get_uk` over a `ResolveCtx`) the applications drive.
-//!
-//! Covered:
-//! - `KeydbSource`: terminal unit-key lookup by disc hash through a real
-//!   `keydb.cfg`; the exe-local path helpers; MKB-aware host-cert serving.
-//! - `OnlineSource`: SSRF/scheme validation and the unconfigured no-op.
-//! - `MultiSource`: caller-supplied ordering / precedence, host-cert UNION,
-//!   and nesting.
+//! real files on disk, the real `KeyDb` parser from libfreemkv, and the
+//! `KeySource` trait (`get_unit_keys` over a `ResolveCtx`) the applications
+//! drive. Covered: `KeydbSource` terminal unit-key lookup by disc hash
+//! (plus exe-local path helpers and MKB-aware host-cert serving);
+//! `OnlineSource` SSRF/scheme validation and the unconfigured no-op; and
+//! `MultiSource` ordering/precedence, host-cert UNION, and nesting.
 
 use std::io::Write;
 use std::path::{Path, PathBuf};
@@ -71,8 +68,8 @@ fn inputs(hash: &str) -> DiscInputs {
 /// Resolve a source through the public trait over a `DiscInputsCtx`.
 fn resolve(src: &dyn KeySource, inp: &DiscInputs) -> Vec<UnitKey> {
     let ctx = DiscInputsCtx::new(inp);
-    src.get_uk(&ctx)
-        .expect("get_uk must not error for these fixtures")
+    src.get_unit_keys(&ctx)
+        .expect("get_unit_keys must not error for these fixtures")
 }
 
 // ── KeydbSource: real-file lookup by disc hash ──────────────────────────────
@@ -130,7 +127,7 @@ fn keydb_source_missing_file_is_silent_ok_empty() {
     let inp = inputs(DISC_HASH);
     let ctx = DiscInputsCtx::new(&inp);
     assert!(
-        src.get_uk(&ctx)
+        src.get_unit_keys(&ctx)
             .expect("missing keydb is Ok, not Err")
             .is_empty()
     );
@@ -141,7 +138,7 @@ fn keydb_source_label_is_keydb() {
     assert_eq!(KeydbSource::new("/nonexistent/keydb.cfg").label(), "keydb");
 }
 
-// ── KeydbSource: MKB-aware host-cert serving from a file ────────────────────
+// ── KeydbSource: host-cert serving from a file ──────────────────────────────
 
 #[test]
 fn keydb_source_serves_host_cert_from_hc_row() {
@@ -155,14 +152,13 @@ fn keydb_source_serves_host_cert_from_hc_row() {
     let path = s.write("keydb.cfg", &line);
 
     let src = KeydbSource::new(&path);
-    // Inherent (no-MKB, scan-options) form.
+    // Inherent (scan-options) form.
     assert_eq!(
         src.host_certs().len(),
         1,
         "inherent host_certs sees the HC row"
     );
-    // Trait form now wires the MKB generation through (no revocation annotation
-    // → always returned).
+    // Trait form: `mkb` is ignored; the ranked list is returned.
     let via_trait = KeySource::host_certs(&src, Some(70));
     assert_eq!(via_trait.len(), 1, "trait host_certs sees the HC row");
     assert_eq!(via_trait[0].certificate.len(), 92);
@@ -232,13 +228,14 @@ fn online_source_metadata() {
 }
 
 #[test]
-fn validate_keyserver_url_gates_scheme_and_ssrf() {
+fn validate_keyserver_url_gates_scheme_and_allows_lan() {
     assert!(validate_keyserver_url("https://8.8.8.8/keys").is_ok());
+    // Home app: LAN/loopback/link-local hosts pass; cleartext http and invalid addresses do not.
+    assert!(validate_keyserver_url("https://127.0.0.1/keys").is_ok());
+    assert!(validate_keyserver_url("https://169.254.1.5/keys").is_ok());
+    assert!(validate_keyserver_url("https://[::1]:9000/keys").is_ok());
     assert!(validate_keyserver_url("http://127.0.0.1/keys").is_err());
-    // SSRF blocking is IP-based, not scheme-gated: https://<private-IP> is rejected too.
-    assert!(validate_keyserver_url("https://127.0.0.1/keys").is_err());
-    assert!(validate_keyserver_url("http://169.254.169.254/latest/meta-data/").is_err());
-    assert!(validate_keyserver_url("http://[::1]:9000/keys").is_err());
+    assert!(validate_keyserver_url("https://0.0.0.0/keys").is_err());
     assert!(validate_keyserver_url("ftp://example.com/keys").is_err());
     assert!(validate_keyserver_url("").is_err());
 }
@@ -258,7 +255,7 @@ impl ScriptedSource {
 }
 
 impl KeySource for ScriptedSource {
-    fn get_uk(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+    fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
         Ok(self.keys.clone())
     }
     fn label(&self) -> &'static str {
@@ -270,6 +267,15 @@ fn uk(b: u8) -> UnitKey {
     UnitKey::new(0, [b; 16])
 }
 
+/// `MultiSource` itself reports a fixed label, distinct from any inner
+/// source's own label — this is what a rip's source-attribution log shows
+/// when the composition, not one of its members, answered.
+#[test]
+fn multi_source_label_is_multi() {
+    let multi = MultiSource::new(vec![Box::new(ScriptedSource::new("A", Vec::new()))]);
+    assert_eq!(multi.label(), "multi");
+}
+
 #[test]
 fn multi_source_first_non_empty_wins_in_caller_order() {
     // Caller supplies [A, B]; A is non-empty so A's keys win.
@@ -362,6 +368,137 @@ fn multi_source_real_keydb_resolves_through_chain() {
     );
 }
 
+// ── MultiSource: a source that could not ANSWER is not a source that said no ─.
+
+/// A source that always fails, with a chosen error — the key-service outage.
+struct FailingSource {
+    err: fn() -> libfreemkv::Error,
+    label: &'static str,
+}
+
+impl KeySource for FailingSource {
+    fn get_unit_keys(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+        Err((self.err)())
+    }
+    fn get_fmts_indexes(&self, _ctx: &dyn ResolveCtx) -> Result<Vec<UnitKey>, libfreemkv::Error> {
+        Err((self.err)())
+    }
+    fn label(&self) -> &'static str {
+        self.label
+    }
+}
+
+fn unavailable() -> libfreemkv::Error {
+    libfreemkv::Error::KeyServiceUnavailable
+}
+
+fn unauthorized() -> libfreemkv::Error {
+    libfreemkv::Error::KeyServiceUnauthorized
+}
+
+#[test]
+fn multi_source_reports_a_source_failure_instead_of_a_clean_no_key() {
+    let multi = MultiSource::new(vec![
+        Box::new(FailingSource {
+            err: unavailable,
+            label: "down",
+        }),
+        Box::new(ScriptedSource::new("empty", vec![])),
+    ]);
+    let err = multi
+        .get_unit_keys(&DiscInputsCtx::new(&inputs("x")))
+        .expect_err("a failed source must not collapse into a clean no-key");
+    assert_eq!(
+        err.code(),
+        libfreemkv::error::E_KEY_SERVICE_UNAVAILABLE,
+        "the composition must surface the service outage"
+    );
+    assert_ne!(
+        err.code(),
+        libfreemkv::error::E_NO_DISC_KEY,
+        "an outage must never be reported as 'this disc has no key'"
+    );
+}
+
+/// The forensic half carried the identical bug and is now driven through the
+/// same helper — pinned separately so a future edit cannot fix one and leave
+/// the other.
+#[test]
+fn multi_source_fmts_indexes_also_preserve_a_source_failure() {
+    let multi = MultiSource::new(vec![Box::new(FailingSource {
+        err: unavailable,
+        label: "down",
+    })]);
+    assert_eq!(
+        multi
+            .get_fmts_indexes(&DiscInputsCtx::new(&inputs("x")))
+            .expect_err("the forensic path must preserve the failure too")
+            .code(),
+        libfreemkv::error::E_KEY_SERVICE_UNAVAILABLE,
+    );
+}
+
+/// A source failure must NOT block the chain: a later source that actually has
+/// the key still wins outright. Pins the other half of the contract, so the fix
+/// cannot be over-applied into "any error aborts the composition".
+#[test]
+fn multi_source_failure_never_blocks_a_later_success() {
+    let multi = MultiSource::new(vec![
+        Box::new(FailingSource {
+            err: unavailable,
+            label: "down",
+        }),
+        Box::new(ScriptedSource::new("real", vec![uk(0xc1)])),
+    ]);
+    assert_eq!(
+        resolve(&multi, &inputs("x")),
+        vec![uk(0xc1)],
+        "a failing first source must not stop the second from resolving"
+    );
+}
+
+/// FIRST failure wins, matching libfreemkv's `source_failure` rule: the
+/// most-preferred source's reason is the one the operator is told about, in the
+/// same order the caller expressed a preference for successes.
+#[test]
+fn multi_source_reports_the_first_failure_not_the_last() {
+    let multi = MultiSource::new(vec![
+        Box::new(FailingSource {
+            err: unauthorized,
+            label: "bad-token",
+        }),
+        Box::new(FailingSource {
+            err: unavailable,
+            label: "down",
+        }),
+    ]);
+    assert_eq!(
+        multi
+            .get_unit_keys(&DiscInputsCtx::new(&inputs("x")))
+            .expect_err("both sources failed")
+            .code(),
+        libfreemkv::error::E_KEY_SERVICE_UNAUTHORIZED,
+        "the first source's failure is the one reported"
+    );
+}
+
+/// The contrast case: every source ANSWERED and none holds a key. That is the
+/// genuine miss, and `E7022` is then the truth — so the fix must not turn an
+/// honest empty into an error.
+#[test]
+fn multi_source_all_sources_answering_empty_is_still_a_clean_no_key() {
+    let multi = MultiSource::new(vec![
+        Box::new(ScriptedSource::new("a", vec![])),
+        Box::new(ScriptedSource::new("b", vec![])),
+    ]);
+    assert!(
+        multi
+            .get_unit_keys(&DiscInputsCtx::new(&inputs("x")))
+            .expect("every source answered; this is a genuine miss")
+            .is_empty()
+    );
+}
+
 /// The `Path`-typed constructor accepts a borrowed path.
 #[test]
 fn keydb_source_accepts_borrowed_path() {