relay-shell 0.1.0__tar.gz → 0.3.0__tar.gz

relay_shell-0.3.0/.claude/settings.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(uv:*)",
+      "Bash(uvx:*)",
+      "Bash(ruff:*)",
+      "Bash(python:*)",
+      "Bash(python3:*)",
+      "Bash(pytest:*)",
+      "Bash(pre-commit run:*)",
+      "Bash(pip list)",
+      "Bash(pip list:*)",
+      "Bash(pip show:*)",
+      "Bash(pip freeze)",
+      "Bash(pipx list)",
+      "Bash(pipx run:*)",
+      "Bash(mypy:*)",
+      "Bash(just:*)",
+      "Bash(bats:*)",
+      "Bash(bash -n:*)",
+      "Bash(bash --version)"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(**/.env)",
+      "Read(**/.env.*)",
+      "Read(**/secrets/**)",
+      "Read(~/.ssh/**)",
+      "Read(~/.aws/**)",
+      "Read(~/.config/gh/**)",
+      "Read(**/*.pem)",
+      "Read(**/id_rsa*)",
+      "Bash(curl:*)",
+      "Bash(wget:*)",
+      "Bash(git push --force)",
+      "Bash(git push --force:*)",
+      "Bash(git push --force-with-lease)",
+      "Bash(git push --force-with-lease:*)",
+      "Bash(git push -f)",
+      "Bash(git push -f:*)"
+    ]
+  }
+}

relay_shell-0.3.0/.env.example

@@ -0,0 +1,107 @@
+# relay-shell configuration. Copy to .env (never commit a real .env).
+# All variables are optional; defaults are shown.
+
+# --- Transport ---
+# stdio | http
+RELAY_SHELL_TRANSPORT=stdio
+RELAY_SHELL_HTTP_HOST=127.0.0.1
+RELAY_SHELL_HTTP_PORT=8080
+
+# --- Limits (bytes / seconds) ---
+RELAY_SHELL_MAX_OUTPUT=65536
+RELAY_SHELL_MAX_OUTPUT_HARD=1048576
+RELAY_SHELL_DEFAULT_TIMEOUT=60
+RELAY_SHELL_MAX_TIMEOUT=900
+RELAY_SHELL_MAX_SESSIONS=64
+RELAY_SHELL_SESSION_IDLE_TIMEOUT=1800
+RELAY_SHELL_SESSION_BUFFER_BYTES=262144
+
+# --- Policy ---
+# open | guarded | readonly
+#   open     : full access (default; matches the documented single-owner posture)
+#   guarded  : Tier 2+ commands are refused unless RELAY_SHELL_POLICY_ALLOW matches
+#   readonly : only Tier 0 (read-only) commands permitted
+RELAY_SHELL_POLICY_MODE=open
+RELAY_SHELL_POLICY_DENY=
+RELAY_SHELL_POLICY_ALLOW=
+
+# --- Tier-3 confirmation broker (ADR 0009) ---
+# Opt-in, default off. When true, a Tier-3 (IRREVERSIBLE) command that already
+# passed the deny list and mode check is not executed on first request: the
+# runner returns a single-use, TTL-bounded token (audited action=confirm_plan,
+# no side effect) and the caller must arm it via the operation_confirm tool,
+# then re-issue the exact same call (audited action=confirm_execute). This is an
+# added safeguard, never a bypass — the deny list and mode policy still run
+# first. Default off keeps the audit record byte-identical.
+RELAY_SHELL_CONFIRM_TIER3=false
+# How long a minted confirmation token stays valid before it must be re-planned.
+# Seconds, 5..3600.
+RELAY_SHELL_CONFIRM_TTL=120
+
+# --- Audit ---
+RELAY_SHELL_AUDIT_PATH=/var/log/relay-shell/audit.jsonl
+RELAY_SHELL_AUDIT_STDERR=false
+# jsonl | cef | leef
+RELAY_SHELL_AUDIT_FORMAT=jsonl
+# Tamper-evident audit (ADR 0007). When true, each record carries seq/prev/chain
+# so an edit, insertion, reorder, or interior deletion of the on-disk log is
+# detectable with `relay-shell --verify-audit` (head-truncation via
+# --require-genesis; tail-truncation and cross-file continuity are the off-host
+# shipper's job). Default off keeps the record byte-identical. Requires
+# RELAY_SHELL_AUDIT_FORMAT=jsonl. Enable on a freshly rotated log for a clean chain.
+RELAY_SHELL_AUDIT_CHAIN=false
+
+# --- Syscall-level audit channel (ADR 0006) ---
+# Opt-in, audit-only seccomp-notify channel. When true, locally-spawned
+# children - one-shot (shell_exec / shell_script / ssh_keyscan) and
+# shell_spawn PTY sessions (the filter rides the session child for the
+# session's life) - get a seccomp-bpf USER_NOTIF filter and one
+# `syscall_notify` audit line is appended per observed syscall (execve,
+# set-uid/namespace/mount changes, write-opens, privilege-relevant prctls).
+# It NEVER blocks a syscall. It activates only when the process holds
+# CAP_SYS_ADMIN (so set-uid/sudo behaviour is preserved verbatim — no
+# no_new_privs is ever latched) on Linux/x86_64 with kernel >= 5.5;
+# otherwise it cleanly no-ops (server_info.seccomp reports why). Default off
+# keeps the spawn path byte-identical.
+RELAY_SHELL_SECCOMP_NOTIFY=false
+# Event cap per spawned child (per call for one-shot tools, per session
+# for shell_spawn). Beyond it, one `syscall_notify_overflow` line is
+# written and emission stops for that child (it still runs to
+# completion). 1..65536.
+RELAY_SHELL_SECCOMP_NOTIFY_CAP=256
+
+# --- SSH ---
+RELAY_SHELL_SSH_CONFIG=~/.ssh/config
+RELAY_SHELL_INVENTORY=
+# strict | accept-new | ignore
+RELAY_SHELL_SSH_KNOWN_HOSTS=accept-new
+RELAY_SHELL_SSH_CONNECT_TIMEOUT=10
+RELAY_SHELL_SSH_KEEPALIVE=30
+# Idle eviction for cached SSH connections (seconds). The pool consults
+# this on every connect() and drops any entry that has not been used in
+# the last N seconds. 0 disables the reaper (a closed connection is
+# still evicted opportunistically).
+RELAY_SHELL_SSH_IDLE_TIMEOUT=1800
+
+# --- Edge TLS (consumed by deploy/install-edge.sh and the Caddyfile) ---
+# Required to issue a public Let's Encrypt certificate:
+RELAY_SHELL_EDGE_DOMAIN=
+RELAY_SHELL_EDGE_ACME_EMAIL=
+# Space-separated source allowlist for tool traffic and /token. Defaults to
+# loopback only, which blocks remote clients until you set this. The value
+# is quoted so it is safe both as a systemd EnvironmentFile entry and as a
+# bash-sourced assignment.
+RELAY_SHELL_EDGE_CLIENT_CIDRS="127.0.0.1/8 ::1"
+# Override only if relay-shell binds a non-default loopback host:port.
+RELAY_SHELL_EDGE_UPSTREAM=127.0.0.1:8080
+# Set to https://acme-staging-v02.api.letsencrypt.org/directory for dry runs.
+RELAY_SHELL_EDGE_ACME_CA=https://acme-v02.api.letsencrypt.org/directory
+
+# --- OAuth 2.1 (HTTP transport only; requires the [http] extra) ---
+RELAY_SHELL_AUTH_ENABLED=false
+RELAY_SHELL_AUTH_ISSUER=https://localhost:8080
+RELAY_SHELL_AUTH_STATE_DIR=/var/lib/relay-shell/oauth
+RELAY_SHELL_AUTH_SINGLE_CLIENT=true
+RELAY_SHELL_AUTH_ACCESS_TTL=3600
+RELAY_SHELL_AUTH_REFRESH_TTL=2592000
+RELAY_SHELL_AUTH_CODE_TTL=300

relay_shell-0.3.0/.github/CODEOWNERS

@@ -0,0 +1,48 @@
+# CODEOWNERS for relay-shell.
+#
+# These rules auto-request review from the listed owner when matching
+# paths change. Without branch protection requiring CODEOWNERS review
+# (Settings -> Branches on github.com), these requests are advisory.
+#
+# The trust-boundary list mirrors docs/runbook.md §3.3; keep the two in
+# sync when adding or removing a security-sensitive surface.
+
+# Default owner: everything routes here unless a more specific rule below wins.
+*                                       @rmednitzer
+
+# Trust boundary (runbook §3.3): policy admission, audit pipeline,
+# secret redaction, the central Relay.run() body, and the auth provider.
+/src/relay_shell/audit.py               @rmednitzer
+/src/relay_shell/redaction.py           @rmednitzer
+/src/relay_shell/policy.py              @rmednitzer
+/src/relay_shell/patterns.py            @rmednitzer
+/src/relay_shell/server.py              @rmednitzer
+/src/relay_shell/metrics.py             @rmednitzer
+/src/relay_shell/verifier.py            @rmednitzer
+/src/relay_shell/auth/                  @rmednitzer
+
+# Deploy + edge: systemd unit, hardening drop-in, Caddyfile (CIDR + headers),
+# installers that write EnvironmentFiles. Any change here lands a
+# privileged-execution artifact on a host.
+/deploy/install.sh                      @rmednitzer
+/deploy/install-edge.sh                 @rmednitzer
+/deploy/Caddyfile                       @rmednitzer
+/deploy/systemd/                        @rmednitzer
+/deploy/logrotate/                      @rmednitzer
+
+# CI / supply chain: workflow definitions, Renovate config, release
+# automation, SBOM generation.
+/.github/                               @rmednitzer
+/.github/workflows/                     @rmednitzer
+/renovate.json5                         @rmednitzer
+/.github/CODEOWNERS                     @rmednitzer
+
+# Project + governance manifests.
+/pyproject.toml                         @rmednitzer
+/requirements.txt                       @rmednitzer
+/SECURITY.md                            @rmednitzer
+/CODE_OF_CONDUCT.md                     @rmednitzer
+/CONTRIBUTING.md                        @rmednitzer
+/AGENTS.md                              @rmednitzer
+/CLAUDE.md                              @rmednitzer
+/docs/adr/                              @rmednitzer

{relay_shell-0.1.0 → relay_shell-0.3.0}/.github/PULL_REQUEST_TEMPLATE.md

@@ -30,7 +30,7 @@ backlog item if applicable: "Closes B-007 from docs/runbook.md". -->
 ## Runbook §3.1 checklist
 
 - [ ] CI is green on the PR head commit (lint, type-check, tests,
-      CodeQL, dependency-review).
+      CodeQL, dependency-review, pip-audit, gitleaks).
 - [ ] No new file is undocumented in `docs/architecture.md` module
       table.
 - [ ] No new tool is missing from `docs/tools.md`,
@@ -43,9 +43,10 @@ backlog item if applicable: "Closes B-007 from docs/runbook.md". -->
 
 ## Security-sensitive diff (runbook §3.3)
 
-Tick if this PR touches any of: `audit.py`, `redaction.py`,
-`policy.py`, the `Relay.run()` body in `server.py`, `auth/oauth.py`,
-`deploy/install*.sh`, or `deploy/Caddyfile`.
+Tick if this PR touches any of: `patterns.py`, `audit.py`, `redaction.py`,
+`policy.py`, the `Relay.run()` body or a resource handler in `server.py`,
+`auth/oauth.py`, `metrics.py`, `seccomp.py`, `deploy/install*.sh`, or
+`deploy/Caddyfile`. (Full list with rationale: runbook §3.3.)
 
 - [ ] This PR is security-sensitive.
 

{relay_shell-0.1.0 → relay_shell-0.3.0}/.github/workflows/ci.yml

@@ -5,6 +5,9 @@ on:
     branches: [main]
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   check:
     permissions:
@@ -21,9 +24,9 @@ jobs:
         python-version: ["3.12", "3.13", "3.14"]
     name: check (py${{ matrix.python-version }})
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"

{relay_shell-0.1.0 → relay_shell-0.3.0}/.github/workflows/codeql.yml

@@ -24,15 +24,15 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4
+        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e  # v4
         with:
           languages: ${{ matrix.language }}
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v4
+        uses: github/codeql-action/autobuild@8aad20d150bbac5944a9f9d289da16a4b0d87c1e  # v4
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v4
+        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e  # v4

relay_shell-0.3.0/.github/workflows/dependency-review.yml

@@ -0,0 +1,26 @@
+name: dependency-review
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      # No checkout step, deliberately (audit finding SEC-2). At the pinned
+      # SHA the action is API-only: for `pull_request` events it takes the
+      # base/head SHAs from the event payload (src/git-refs.ts) and calls the
+      # Dependency Graph compare API (src/main.ts); it spawns no git process
+      # and never reads the working tree unless a local `config-file` input
+      # is used (we pass none). Verified against the action source at this
+      # SHA, 2026-06-12. Dropping the checkout removes the persisted-token
+      # surface a checkout would add and the repo bytes on disk. If a future
+      # bump starts needing the workspace, this job fails loudly on the PR
+      # that bumps it; restore a checkout WITHOUT `persist-credentials: true`
+      # and re-verify, rather than reverting to the credential helper.
+      - name: Dependency review
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294  # v5.0.0

relay_shell-0.3.0/.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: docs
+
+# Build the MkDocs Material documentation site from docs/ and publish it to
+# GitHub Pages. Requires a one-time repo setting:
+#   Settings -> Pages -> Build and deployment -> Source: "GitHub Actions"
+# (this replaces the former Jekyll "Deploy from a branch" source).
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# Least-privilege default; the deploy job adds only the Pages-specific scopes.
+permissions:
+  contents: read
+
+# One Pages deployment at a time; let an in-flight publish finish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build (MkDocs Material)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+      - name: Install MkDocs Material
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-docs.txt
+      - name: Build site (strict)
+        run: mkdocs build --strict
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5
+        with:
+          path: site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write # publish the Pages deployment
+      id-token: write # OIDC token required by deploy-pages
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128  # v5

relay_shell-0.3.0/.github/workflows/gitleaks.yml

@@ -0,0 +1,73 @@
+name: gitleaks
+
+# Secret scan of the working tree and full git history on every PR + push to
+# main, plus a daily rerun so a credential committed between releases surfaces
+# within 24h. This repository is a redaction tool and deliberately ships
+# *synthetic* secret-shaped fixtures (tests, the runbook redaction sample, the
+# audit evidence); `.gitleaks.toml` allowlists exactly those documented paths,
+# so a finding here means a real secret reached a non-fixture location (e.g.
+# under `src/`). See `.gitleaks.toml` and audit finding S-004/TOOL-1.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # 04:47 UTC daily. The odd minute mirrors nightly-fuzz / pip-audit so the
+    # security signals cluster together in the activity timeline.
+    - cron: "47 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    name: gitleaks (secret scan)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout (full history so the scan covers every commit)
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
+        with:
+          fetch-depth: 0
+
+      - name: Install gitleaks (pinned, checksum-verified)
+        env:
+          # Bump together with any local-tooling expectation; gitleaks is
+          # feature-complete, so updates are security patches only.
+          GITLEAKS_VERSION: "8.30.1"
+        run: |
+          set -euo pipefail
+          base="https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}"
+          # Download the release's own checksums file, then discover the exact
+          # linux x64/amd64 tarball name from it (the arch token has changed
+          # across gitleaks releases). This avoids hardcoding a checksum here
+          # and fails loudly on any name/integrity mismatch.
+          curl -fsSL -o checksums.txt "${base}/gitleaks_${GITLEAKS_VERSION}_checksums.txt"
+          tarball="$(grep -oE "gitleaks_${GITLEAKS_VERSION}_linux_(x64|amd64)\.tar\.gz" checksums.txt | head -1)"
+          if [ -z "${tarball}" ]; then
+            echo "could not find a linux x64/amd64 asset in the checksums file" >&2
+            cat checksums.txt >&2
+            exit 1
+          fi
+          curl -fsSL -o "${tarball}" "${base}/${tarball}"
+          # Verify the downloaded tarball against the exact line in the
+          # checksums file (field 2 == filename) before extracting anything.
+          awk -v f="${tarball}" '$2 == f' checksums.txt | sha256sum --check -
+          tar -xzf "${tarball}" gitleaks
+          install -m 0755 gitleaks /usr/local/bin/gitleaks
+          rm -f "${tarball}" checksums.txt gitleaks
+          gitleaks version
+
+      - name: Run gitleaks
+        run: |
+          # Default exit code 1 on any finding fails the job. `.gitleaks.toml`
+          # (config auto-discovered at the repo root, passed explicitly here
+          # for clarity) allowlists only the synthetic-fixture paths.
+          gitleaks detect \
+            --source . \
+            --config .gitleaks.toml \
+            --no-banner \
+            --redact \
+            --verbose

{relay_shell-0.1.0 → relay_shell-0.3.0}/.github/workflows/nightly-fuzz.yml

@@ -22,11 +22,11 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
         with:
-          python-version: "3.12"
+          python-version: "3.14"
           cache: "pip"
 
       - name: Install

relay_shell-0.3.0/.github/workflows/pip-audit.yml

@@ -0,0 +1,53 @@
+name: pip-audit
+
+# CVE scan of the resolved Python dependency tree on every PR + push to
+# main, plus a daily rerun so a CVE landing against a pinned dep
+# surfaces within 24h instead of waiting for the next release-time
+# audit. dependency-review-action (on PR) only reviews *added*
+# dependencies; pip-audit covers the whole graph.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # 04:35 UTC daily. The odd minute mirrors nightly-fuzz so the audit
+    # signals appear close together in the activity timeline.
+    - cron: "35 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    name: pip-audit (CVE scan)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
+        with:
+          python-version: "3.14"
+          cache: "pip"
+
+      - name: Install package + dev extras
+        run: |
+          python -m pip install --upgrade pip pip-audit
+          # Audit against the resolved dev set so transitive deps
+          # introduced via the optional [dev] / [http] extras are also
+          # covered.
+          pip install -e ".[dev,http]"
+
+      - name: Run pip-audit
+        # `--skip-editable` excludes the local editable `relay-shell` install:
+        # pip-audit resolves each distribution on PyPI for known CVEs, but the
+        # project itself is not a third-party dependency to audit, and an
+        # unreleased in-repo version (e.g. a release-prep bump before the tag is
+        # published) is not on PyPI. `--strict` is intentionally NOT combined
+        # with it: --strict treats the skipped editable project as an incomplete
+        # audit and fails ("distribution marked as editable"). Every actual
+        # third-party dependency (incl. the [dev]/[http] extras) is on PyPI and
+        # still audited, and pip-audit still exits non-zero on any CVE found.
+        run: pip-audit --skip-editable

{relay_shell-0.1.0 → relay_shell-0.3.0}/.github/workflows/release.yml

@@ -66,11 +66,15 @@ jobs:
       # without this `ref` would compare the tag against whatever version
       # currently sits on the default branch and falsely reject a valid
       # signed tag.
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
         with:
           ref: ${{ steps.tag.outputs.tag }}
           fetch-depth: 0
-          persist-credentials: true
+          # No step after checkout uses git auth (the tag signature is
+          # verified via the REST API with an explicit GH_TOKEN, and the
+          # version check reads the working tree), so do not persist the
+          # token in .git/config (CI-2 finding; matches the SEC-2 posture).
+          persist-credentials: false
 
       - name: Assert tag matches pyproject version (at the tagged commit)
         id: version
@@ -124,14 +128,23 @@ jobs:
     needs: verify
     runs-on: ubuntu-latest
     timeout-minutes: 20
+    permissions:
+      # Sigstore OIDC + attestation publishing for the SLSA v1.2 Build
+      # Track L3 provenance attestation produced below. Job-level
+      # `permissions:` REPLACES the workflow-level `contents: read`
+      # default, so keep `contents: read` explicit (we don't need any
+      # broader write).
+      contents: read
+      id-token: write
+      attestations: write
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
         with:
           ref: ${{ needs.verify.outputs.release_commit }}
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
         with:
-          python-version: "3.12"
+          python-version: "3.14"
           cache: "pip"
 
       - name: Install package + build backend
@@ -151,8 +164,19 @@ jobs:
           pip install twine
           twine check dist/*
 
+      - name: Generate SLSA Build Provenance attestation
+        # Produces a Sigstore-signed in-toto attestation linking the
+        # workflow run + commit SHA to every artifact under dist/.
+        # Closes the SLSA v1.2 Build Track L3 gap (Phase-3 cross-check):
+        # PyPI OIDC trusted publishing already provides L2; this step
+        # adds a verifier-checkable provenance record in Sigstore's
+        # public transparency log.
+        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373  # v4
+        with:
+          subject-path: 'dist/*'
+
       - name: Upload artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
           name: dist-${{ needs.verify.outputs.version }}
           path: dist/
@@ -176,13 +200,13 @@ jobs:
       actions: read
       contents: read
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
         with:
           name: dist-${{ needs.verify.outputs.version }}
           path: dist/
 
       - name: Publish via PyPI trusted publishing
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
         with:
           # Make a workflow re-run after a successful upload idempotent
           # instead of failing on "file already exists" - the runbook