floorvault 0.1.0__tar.gz

floorvault-0.1.0/.clusterfuzzlite/Dockerfile

@@ -0,0 +1,9 @@
+# ClusterFuzzLite build image for FloorVault's Atheris fuzz targets (fuzz/).
+#
+# Pinned by digest: the base image carries the fuzzing toolchain (Atheris,
+# libFuzzer, the sanitizer runtimes), so a moving tag would let the thing that
+# decides "no crash found" change underneath an unchanged repository.
+FROM gcr.io/oss-fuzz-base/base-builder-python@sha256:58f80c90a90944b68b8e70b98e38997ee9396225311cfb0f3aea78671446ab4e
+COPY . $SRC/floorvault
+WORKDIR $SRC/floorvault
+COPY .clusterfuzzlite/build.sh $SRC/

floorvault-0.1.0/.clusterfuzzlite/build.sh

@@ -0,0 +1,15 @@
+#!/bin/bash -eu
+# Build every Atheris fuzz target in fuzz/ for ClusterFuzzLite.
+#
+# Installs FloorVault from this checkout (not from PyPI), so the fuzzers exercise
+# the code under review, then packages each target with the seed corpus it
+# declares in seed_inputs(). A target added to fuzz/ is picked up automatically;
+# tests/test_fuzz_targets.py pins that this glob covers them all.
+
+pip3 install --no-cache-dir "$SRC/floorvault"
+
+for fuzzer in "$SRC"/floorvault/fuzz/fuzz_*.py; do
+  name="$(basename -s .py "$fuzzer")"
+  compile_python_fuzzer "$fuzzer"
+  python3 "$SRC/floorvault/fuzz/write_seed_corpus.py" "$fuzzer" "$OUT/${name}_seed_corpus.zip"
+done

floorvault-0.1.0/.clusterfuzzlite/project.yaml

@@ -0,0 +1 @@
+language: python

floorvault-0.1.0/.dockerignore

@@ -0,0 +1,5 @@
+.venv/
+dist/
+build/
+**/__pycache__/
+.pytest_cache/

floorvault-0.1.0/.gitattributes

@@ -0,0 +1,18 @@
+# Normalise line endings for every text file in the repository.
+#
+# Without this the checked-out bytes depend on the platform: git's Windows
+# default (core.autocrlf=true, which is also what the GitHub Windows runners use)
+# rewrites text files to CRLF. The build then packs those CRLF bytes, so the
+# wheel and sdist differ from a POSIX build of the same commit - two digests for
+# one source tree, and no way to check a download against a build from source.
+#
+# eol=lf forces LF on checkout everywhere, so the artifact is at least a function
+# of the source rather than of the machine that checked it out.
+#
+# What this does NOT fix: the archive records the file mode it sees on the
+# filesystem (measured: a source file chmod 0755 produces a different wheel than
+# the same file at 0644), and Windows cannot represent POSIX modes. Byte-identity
+# *across* operating systems is therefore not claimed anywhere; the digest
+# identifies the artifact for a given platform. See tests/test_release_artifacts.py
+# and Appendix B of the third-party review report.
+* text=auto eol=lf

floorvault-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,67 @@
+# Copilot review instructions — FloorVault
+
+FloorVault is contextual, misuse-resistant database encryption (AES-256-SIV
+with coordinate-bound AAD). Reviews here are security reviews first, style
+reviews second.
+
+## Hard rules — flag any violation
+
+- **Never weaken authentication.** The AEAD associated-data vector is
+  `[aad, header, nonce]` for v2 envelopes and `[aad, nonce]` for v1. Every
+  cleartext envelope field must stay inside that vector. Removing an element,
+  reordering, or mutating cleartext fields is a critical finding.
+- **Never remove or weaken validation.** Rejection rules in `docs/SPEC.md`
+  §4.3/§16 are normative, including their ORDER. Do not suggest relaxing a
+  check for convenience.
+- **Nonce discipline.** Nonces are 16 bytes from `os.urandom`, fresh per
+  field. Counter-derived, reused, or truncated nonces are critical findings.
+  The dedup window is defence-in-depth, not a freshness mechanism.
+- **No key/custody downgrades.** A broken or refused custody tier must raise,
+  never silently fall through to a weaker one. No-clobber store publication
+  (hard link) is deliberate; do not suggest `os.replace`.
+- **SQL identifiers** must pass `_safe_identifier` and be interpolated via
+  `_quoted_identifier` (bracket-quoted). Any other interpolation of a name
+  into SQL is a finding.
+- **On-disk formats are a contract** (`docs/SPEC.md`). Byte-level changes
+  require a version bump AND a reader for every documented version. Flag any
+  wire-format change without a spec + vector update.
+- **Tombstones/retirement** are fail-closed: a migrated id is never served
+  from the legacy source again, even if the modern record is gone.
+
+## Conventions
+
+- Errors are honest: no swallowed exceptions, no "cannot tell is fine", no
+  masking one check behind another (the mutation suite hunts these).
+- New security guards get a curated mutant in `scripts/mutation_check.py`;
+  platform-equivalent survivors are declared, not silently skipped.
+- Comments and docstrings explain *why*, and state limits plainly. Correct an
+  outdated claim rather than leave it — this codebase treats wrong docs as
+  bugs (see `docs/SPEC.md` §17).
+- `json.dumps` for authenticated data uses `ensure_ascii=False`,
+  `sort_keys=True`, `separators=(",", ":")`; payload JSON uses default
+  separators. They are NOT interchangeable.
+- Style: ruff clean, compact, no unnecessary try/except — error boundaries
+  follow the existing pattern.
+
+## Frozen quirks — flag these too, and weigh them in every review
+
+These behaviors are deliberate *today* (documented and frozen in
+`docs/SPEC.md`), but they are not above scrutiny. Flag them when they appear
+in a diff or are relevant to a change, note that the design intent is known,
+and assess whether the change under review makes the quirk riskier — e.g.
+new code that relies on one of these edge cases is worth a comment even
+though the behavior itself is intentional:
+
+- `memoryview` plaintext input is refused; `bytearray` envelope input is
+  snapshotted once before parsing (§4.3). Intentional — snapshot safety.
+- Negative or >64-bit `schema_version`/`revision` integers serialize into
+  the AAD (§5.2). Frozen quirk — any tightening must be write-side only so
+  existing records stay readable.
+- `record_id=" r "` (whitespace-padded) is accepted verbatim; only
+  whitespace-only strings are refused (frozen).
+- Integer subclasses in coordinate ints are serialized via `int.__repr__`,
+  not `str()` — the fast path exists specifically so a subclass cannot
+  inject bytes into the AAD. Any new serialization path must keep that.
+- Nonce dedup is in-process only (deque+set window): it does not survive
+  restart and is not a freshness mechanism — `revision` bound into the AAD
+  is. Flag anything that treats the window as stronger.

floorvault-0.1.0/.github/workflows/README-cbom-workflow-removed-2026-09-15.md

@@ -0,0 +1,27 @@
+# Crypto Bill of Materials workflow — removed 2026-09-15
+
+The `.github/workflows/main.yml` "Create Crypto Bill of Materials" workflow,
+added in commit `7ca3499`, was removed in `18de92f` (this file's parent).
+
+**Reason.** The workflow consumed `advanced-security/cbom-action@v1`, which
+internally uses the now-deprecated `actions/upload-artifact: v3`. GitHub
+auto-blocks requests to that deprecated action, so every matrix-analysis job
+(and therefore the whole workflow) failed on every run, including the first
+run after the workflow was added and again on the push that included this
+removal. The failure was in the third-party action's own machinery, not in
+anything `vaultfloor/floorvault` ships.
+
+**What the workflow did.** It used the GitHub Advanced Security CBOM action to
+build a crypto bill of materials across a matrix of public Python ecosystem
+repositories (`coveragepy`, `cryptography`, `ruff`, `packaging`, `pytest`,
+`pyobjc`, etc.), not floorvault's own dependencies in any actionable sense.
+
+**What was already covering the real gate.** FloorVault's secret scan is
+gitleaks in `.github/workflows/ci.yml` (CI job `secret scan (history)`), which
+runs on every push to `main` and must pass for the push to be considered
+gate-clean. The CBOM workflow was informational only and was never part of the
+pre-push gate.
+
+**Status.** Removed. No replacement is in place; if a crypto bill of materials
+is wanted in future it should use a maintained action whose dependencies do not
+include a deprecated artifact-action version.

floorvault-0.1.0/.github/workflows/cflite-prune.yml

@@ -0,0 +1,43 @@
+name: ClusterFuzzLite Corpus Prune
+
+on:
+  workflow_run:
+    workflows: [ClusterFuzzLite]
+    types: [completed]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  actions: read
+
+concurrency:
+  group: cflite-prune-main
+  cancel-in-progress: false
+
+jobs:
+  # Corpus pruning is required alongside batch fuzzing: without it the artifact-
+  # persisted corpus grows unboundedly. Runs after the weekly batch or by manual dispatch.
+  prune:
+    name: corpus prune (weekly)
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.workflow_run.event == 'schedule' &&
+       github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.head_branch == 'main' &&
+       github.event.workflow_run.head_repository.full_name == github.repository)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build fuzzers
+        uses: google/clusterfuzzlite/actions/build_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          language: python
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          sanitizer: address
+
+      - name: Prune corpus
+        uses: google/clusterfuzzlite/actions/run_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          sanitizer: address
+          mode: prune
+          fuzz-seconds: 600

floorvault-0.1.0/.github/workflows/cflite.yml

@@ -0,0 +1,60 @@
+name: ClusterFuzzLite
+
+# Coverage-guided fuzzing of the Atheris targets in fuzz/ (envelope parsing,
+# canonical AAD, the protected key-store reader, SQL identifier validation and
+# beacon encoding). Build integration lives in .clusterfuzzlite/.
+#
+# Pull requests fuzz for 5 minutes in code-change mode, so a crash introduced by
+# the PR fails it. Pushes to main and a weekly schedule run longer batch fuzzing.
+# With no storage repo configured, ClusterFuzzLite persists the corpus as GitHub
+# Actions artifacts: each batch run downloads the previous run's corpus-*
+# artifacts (that is what the actions: read permission is for) and uploads the
+# grown corpus. Weekly pruning runs in a separate follow-on workflow
+# (cflite-prune.yml) after the completed batch, so the persisted corpus stays
+# minimized instead of growing unboundedly.
+#
+# The private repository needs the token passed to both steps.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "41 2 * * 0"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  fuzz:
+    name: fuzz (${{ github.event_name == 'pull_request' && 'code-change' || 'batch' }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # Lets run_fuzzers list previous runs' artifacts (corpus, builds); without
+      # it the download fails with 403 and every run starts from the seeds.
+      actions: read
+    concurrency:
+      group: cflite-${{ github.ref }}
+      cancel-in-progress: true
+    steps:
+      - name: Build fuzzers
+        uses: google/clusterfuzzlite/actions/build_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          language: python
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          sanitizer: address
+
+      - name: Run fuzzers
+        uses: google/clusterfuzzlite/actions/run_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          sanitizer: address
+          mode: ${{ github.event_name == 'pull_request' && 'code-change' || 'batch' }}
+          fuzz-seconds: ${{ github.event_name == 'pull_request' && 300 || 1800 }}
+          # Fail on a crash even when the reproduction step cannot confirm it.
+          # Python fuzzer start-up is slow enough that reproduction can time out;
+          # the first run of this workflow found a real crash, failed to
+          # reproduce it for exactly that reason, discarded it, and went green.
+          report-unreproducible-crashes: true

floorvault-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,236 @@
+name: CI
+
+# Runs the same security gates developers run before pushing
+# (scripts/security-check.sh) across every supported OS and Python version, so
+# the cross-platform and "zero C compilation" claims are exercised on every
+# push rather than only on a maintainer's machine.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # Python-version sweep on Linux (regressions here are platform-independent),
+  # plus one macOS and one Windows runner for the OS-specific code paths.
+  gates:
+    name: ${{ matrix.os }} / py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Linux: the full supported range.
+          - { os: ubuntu-latest, python: "3.10" }
+          - { os: ubuntu-latest, python: "3.11" }
+          - { os: ubuntu-latest, python: "3.12" }
+          - { os: ubuntu-latest, python: "3.13" }
+          - { os: ubuntu-latest, python: "3.14" }
+          # macOS and Windows: BOTH ends of the range, not just the default.
+          # A platform-specific code path can be fine on the newest interpreter
+          # and broken on the oldest (or the reverse), and every defect the
+          # matrix has found so far was platform-specific; see
+          # docs/CROSS-PLATFORM-CI-FINDINGS-2026-09-15.md. 3.10 is the floor
+          # declared in pyproject.toml, so it must be exercised on every OS.
+          - { os: macos-latest, python: "3.10" }
+          - { os: macos-latest, python: "3.13" }
+          - { os: windows-latest, python: "3.10" }
+          - { os: windows-latest, python: "3.13" }
+    steps:
+      # fetch-depth: 0 is required because gitleaks scans history, not just the
+      # tip; a shallow checkout would make the scan meaningless.
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv and Python ${{ matrix.python }}
+        # Pinned to a full version: setup-uv only maintains moving major tags up
+        # to v7; v8+ exist as full versions only (v10 does not resolve).
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+          # Pin the uv binary too: setup-uv otherwise resolves its latest
+          # release, so the tool building the artifacts would move even with
+          # the action pinned by SHA.
+          version: "0.12.5"
+
+      - name: Sync environment
+        shell: bash
+        run: |
+          if [ "${{ runner.os }}" = "macOS" ]; then
+            # Keychain (Tier 2 of the adaptive provider) needs the Security bindings.
+            uv sync --extra dev --extra macos
+          else
+            uv sync --extra dev
+          fi
+          # The gate audits dependencies with pip-audit; install it into the venv
+          # so require_tool finds it under FLOORVAULT_STRICT=1 on every OS.
+          uv pip install pip-audit
+
+      - name: Run security gates
+        shell: bash
+        env:
+          FLOORVAULT_STRICT: "1"
+          # History is identical on every runner, so the secret scan runs once,
+          # in the `secrets` job below.
+          FLOORVAULT_SKIP_SECRET_SCAN: "1"
+          # Same reasoning for Semgrep: it runs once, in the `sast` job below.
+          FLOORVAULT_SKIP_SEMGREP: "1"
+        run: bash scripts/security-check.sh
+
+      # Publish one leg's artifacts as the release identity. The gate prints the
+      # digests of what it built on EVERY leg (step 11), so the other platforms
+      # stay comparable from the logs; this step exists so that a released wheel
+      # can be checked against a CI-built artifact rather than only against a
+      # maintainer's machine. One leg only: ten legs publishing the same name
+      # would collide, and upload-artifact cannot merge them meaningfully.
+      - name: Publish the built artifacts
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.13'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: floorvault-dist
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          # Fail closed: an upload step that silently publishes nothing is worse
+          # than no step at all, because it looks like the artifact was captured.
+          if-no-files-found: error
+
+  # Secret scanning over full history, once, on Linux.
+  #
+  # This runs the gitleaks CLI rather than `gitleaks/gitleaks-action`: the Action
+  # requires a licence for ORGANIZATION-owned repositories, and this repository
+  # moved into the `vaultfloor` organization, at which point the job started
+  # failing with "License key is required" and - because the workflow cancels
+  # in-progress runs - cancelled five other legs with it. The CLI has no such
+  # gate, runs exactly the command the local gate runs, and removes one
+  # third-party action from the supply chain.
+  #
+  # The download is version-pinned and checksum-verified: a scanner that cannot
+  # be verified must not silently become the thing that certifies everything else.
+  secrets:
+    name: secret scan (history)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
+        with:
+          # A shallow checkout would make a history scan meaningless.
+          fetch-depth: 0
+      - name: Install gitleaks (pinned, checksum-verified)
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION=8.30.1
+          ASSET="gitleaks_${VERSION}_linux_x64.tar.gz"
+          SHA256=551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb
+          curl -sSfL -o "$ASSET" \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${VERSION}/${ASSET}"
+          echo "${SHA256}  ${ASSET}" | sha256sum -c -
+          tar -xzf "$ASSET" gitleaks
+          sudo install -m 0755 gitleaks /usr/local/bin/gitleaks
+          gitleaks version
+      - name: Scan history for secrets
+        shell: bash
+        # Same command as step 1 of scripts/security-check.sh, so CI and a local
+        # run agree on what the scan is. Non-zero exit when a secret is found.
+        run: gitleaks git --verbose --redact
+
+  # Static application security testing, once, on Linux.
+  #
+  # Bandit also runs on every matrix leg inside the gate (it is a dev dependency);
+  # it is repeated here so this job is a complete SAST record on its own. Semgrep
+  # is pinned to an exact version, but the p/python registry ruleset is fetched
+  # at run time and is not versioned: a newly published rule can fail this job
+  # without a code change. That is deliberate - a new rule that fires is a new
+  # finding to review - and it is why Semgrep runs here rather than on every leg.
+  sast:
+    name: SAST (Bandit, Semgrep CE)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4
+        with:
+          python-version: "3.13"
+          version: "0.12.5"
+      - name: Sync environment
+        run: uv sync --extra dev
+      - name: Bandit
+        # Same command as step 3a of scripts/security-check.sh.
+        run: uv run bandit -q -r src/ scripts/ fuzz/
+      - name: Semgrep CE
+        # Same command as step 3b of scripts/security-check.sh.
+        run: |
+          SEMGREP_VERSION=1.178.0
+          uvx --from "semgrep==${SEMGREP_VERSION}" semgrep scan --config p/python --metrics=off --error src/ scripts/ fuzz/
+
+  # Live-Vault integration leg (roadmap 1f): the hermetic fake-Vault suite can
+  # encode a wrong wire assumption in lockstep with the implementation — a real
+  # TLS-terminated Vault cannot. This runs the provider end-to-end against a
+  # dev server with verified TLS (the provider refuses plain HTTP by design).
+  #
+  # The Vault binary is version-pinned and checksum-verified for the same
+  # reason gitleaks is: a tool certifying the contract must itself be verified.
+  # The root token is a throwaway CI literal for an in-memory dev server that
+  # dies with the job — it is not a credential.
+  vault-live:
+    name: vault transit (live dev server)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4
+        with:
+          python-version: "3.13"
+          version: "0.12.5"
+      - name: Sync environment
+        run: uv sync --extra dev
+      - name: Install Vault (pinned, checksum-verified)
+        run: |
+          set -euo pipefail
+          VERSION=2.1.1
+          ASSET="vault_${VERSION}_linux_amd64.zip"
+          SHA256=8aa90f9cea46f541fc7baa3d0ec692fc06afde9a248cc1f2dcac46a567c6f56b
+          curl -sSfL -o "$ASSET" \
+            "https://releases.hashicorp.com/vault/${VERSION}/${ASSET}"
+          echo "${SHA256}  ${ASSET}" | sha256sum -c -
+          unzip -q "$ASSET" vault
+          sudo install -m 0755 vault /usr/local/bin/vault
+          vault version
+      - name: Start Vault dev server (TLS) and provision the transit key
+        run: |
+          set -euo pipefail
+          mkdir -p "$RUNNER_TEMP/vault-tls"
+          nohup vault server -dev -dev-tls \
+            -dev-tls-cert-dir="$RUNNER_TEMP/vault-tls" \
+            -dev-root-token-id=fv-ci-token \
+            -dev-listen-address=127.0.0.1:8200 \
+            >"$RUNNER_TEMP/vault-dev.log" 2>&1 &
+          export VAULT_ADDR="https://127.0.0.1:8200"
+          export VAULT_CACERT="$RUNNER_TEMP/vault-tls/vault-ca.pem"
+          export VAULT_TOKEN="fv-ci-token"
+          for i in $(seq 1 30); do
+            vault status -format=json >/dev/null 2>&1 && break
+            [ "$i" = 30 ] && { cat "$RUNNER_TEMP/vault-dev.log"; exit 1; }
+            sleep 1
+          done
+          vault secrets enable transit
+          vault write transit/keys/floorvault-ci type=aes256-gcm96 derived=true
+      - name: Run the live-Vault contract test
+        env:
+          FLOORVAULT_LIVE_VAULT: "1"
+          VAULT_ADDR: "https://127.0.0.1:8200"
+          VAULT_CACERT: ${{ runner.temp }}/vault-tls/vault-ca.pem
+          VAULT_TOKEN: fv-ci-token
+        run: uv run pytest -q tests/test_vault_transit_live.py

floorvault-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,139 @@
+name: Release
+
+# Drafted release/provenance controls (roadmap 0e). Two modes:
+#
+#   workflow_dispatch  - rehearsal: build, reproducible-build check, SBOM,
+#                        artifact provenance attestation. Nothing is published.
+#   release: published - the same build, then PyPI publish via Trusted
+#                        Publishing with PEP 740 (Sigstore) attestations.
+#
+# Publishing stays inert until the maintainer completes the owner-side setup in
+# docs/RELEASING.md (PyPI project + Trusted Publisher entry for this workflow,
+# the `pypi` GitHub environment). Until then a real release run fails loudly at
+# the publish step rather than silently skipping it.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  dist:
+    name: Build, verify, attest
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # artifact attestation signs via Sigstore OIDC
+      attestations: write
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4
+        with:
+          python-version: "3.13"
+          version: "0.12.5"
+
+      - name: Build release artifacts twice
+        # The comparison copy MUST be built outside the checkout: the sdist is
+        # VCS-aware, so a second in-repo out-dir appears mid-build and packages
+        # itself into the archive it is producing (dist-second/.gitignore was
+        # the first live demonstration). A mktemp dir can never self-include.
+        run: |
+          set -euo pipefail
+          uv build --out-dir dist
+          SECOND="$(mktemp -d /tmp/floorvault-dist-second.XXXXXX)"
+          uv build --out-dir "$SECOND"
+          echo "SECOND=$SECOND" >> "$GITHUB_ENV"
+
+      - name: Reproducible-build check
+        # Same runner, same source, same toolchain: the digests must match
+        # byte-for-byte. Cross-PLATFORM identity is explicitly not claimed
+        # (SECURITY.md), but a single-environment build that cannot reproduce
+        # itself indicates the toolchain picked up nondeterminism.
+        run: |
+          set -euo pipefail
+          python - "$SECOND" <<'PY'
+          import hashlib
+          import pathlib
+          import sys
+
+          first = {p.name: hashlib.sha256(p.read_bytes()).hexdigest() for p in pathlib.Path("dist").iterdir()}
+          second = {p.name: hashlib.sha256(p.read_bytes()).hexdigest() for p in pathlib.Path(sys.argv[1]).iterdir()}
+          mismatched = sorted(n for n in set(first) | set(second) if first.get(n) != second.get(n))
+          if mismatched:
+              for name in mismatched:
+                  print(f"mismatch {name}: {first.get(name)} != {second.get(name)}", file=sys.stderr)
+              sys.exit(1)
+          for name, digest in sorted(first.items()):
+              print(f"[REPRODUCIBLE] sha256 {digest} {name}")
+          PY
+
+      - name: Verify universal wheel shape
+        run: python scripts/verify_wheel.py dist
+
+      - name: Generate CycloneDX SBOM
+        # The SBOM describes what a consumer installs: a runtime-only sync, not
+        # the dev extras. cyclonedx-bom is version-pinned and >7 days old.
+        # It lives OUTSIDE dist/: the publish job uploads everything in dist/
+        # to PyPI, and a JSON file is not a valid distribution.
+        run: |
+          set -euo pipefail
+          uv sync
+          mkdir -p sbom
+          uvx --from "cyclonedx-bom==7.4.0" \
+            cyclonedx-py environment .venv -o sbom/floorvault-sbom.cdx.json --of JSON \
+            --mc-type library --pyproject pyproject.toml --output-reproducible
+
+      - name: Publish the built artifacts
+        # Two artifacts, not one: a multi-path upload keeps both directory
+        # names at the artifact root, so a single-artifact download would land
+        # sbom/ inside the publish job's dist/ - and the PyPI action uploads
+        # every file it finds there, which a JSON SBOM is not.
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: floorvault-release-dist
+          path: dist/
+          if-no-files-found: error
+
+      - name: Publish the SBOM
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: floorvault-release-sbom
+          path: sbom/
+          if-no-files-found: error
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8
+        with:
+          subject-path: dist/
+
+  publish:
+    name: Publish to PyPI (Trusted Publishing)
+    needs: dist
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # Trusted Publishing exchanges this OIDC token for PyPI
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
+        with:
+          name: floorvault-release-dist
+          path: dist
+
+      - name: Drop uv's out-dir marker
+        # `uv build --out-dir` writes a `.gitignore` into the directory; it is
+        # not a distribution and the PyPI action rejects unknown files.
+        run: rm -f dist/.gitignore
+
+      - name: Publish with PEP 740 attestations
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33
+        with:
+          attestations: true
+          print-hash: true
+          verbose: true