skcomms 0.2.2__tar.gz → 0.2.4__tar.gz

skcomms-0.2.4/.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm derives the version from the git tag, so a
+          # shallow checkout would yield a placeholder like 0.1.dev1 and
+          # break dependency resolution against pinned siblings.
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        # -c constraints.txt pins every dependency to the versions this repo
+        # validated, so CI does not silently drift onto newer releases.
+        run: pip install -c constraints.txt -e ".[crypto,dev,pqc]"
+      # skcomms does NOT depend on skcapstone (that would invert the direction),
+      # but tests/test_integration.py exercises "integrated" mode and assumed a
+      # dev venv where skcapstone happens to be installed. In CI it is not, so
+      # those tests errored with ModuleNotFoundError instead of testing anything.
+      # skcoord is named too (skcapstone.coordination is a re-export shim over it),
+      # and skcot, which backs geo_store.SkcotGeoStore and is git-only (not on PyPI,
+      # not declared), so CI could never have exercised the skcot bridge. --no-deps
+      # also stops this dragging a published skcomms over the checkout under test.
+      - name: Install skcapstone (optional integration backbone) from source
+        run: |
+          pip install --no-deps --no-cache-dir \
+            "skcapstone @ git+https://github.com/smilinTux/skcapstone" \
+            "skcoord @ git+https://github.com/smilinTux/skcoord" \
+            "skcot @ git+https://github.com/smilinTux/skcot" \
+            "capauth @ git+https://github.com/smilinTux/capauth"
+      - name: Run tests with coverage
+        run: python -m pytest tests/ -v --tb=short --cov=skcomms --cov-report=xml --cov-report=term-missing
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm derives the version from the git tag, so a
+          # shallow checkout would yield a placeholder like 0.1.dev1 and
+          # break dependency resolution against pinned siblings.
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # Versions come from constraints.txt (black==26.5.1, ruff==0.15.21),
+      # which already does the pinning correctly. Do NOT re-pin them inline:
+      # naming a different version here makes pip unsolvable against the
+      # constraint file, which fails the job on install before it lints
+      # anything at all.
+      - name: Install lint tools
+        run: pip install -c constraints.txt black ruff
+      - name: Check formatting
+        run: black --check src/ tests/
+      - name: Lint
+        run: ruff check src/
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm derives the version from the git tag, so a
+          # shallow checkout would yield a placeholder like 0.1.dev1 and
+          # break dependency resolution against pinned siblings.
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel and sdist
+        run: |
+          pip install build
+          python -m build
+      - name: Check dist
+        run: |
+          pip install twine
+          twine check dist/*

skcomms-0.2.4/.github/workflows/publish.yml

@@ -0,0 +1,134 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: ["main"]
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Trusted Publishing (OIDC) is configured on PyPI for this project:
+#   owner=smilinTux  workflow=publish.yml  environment=pypi
+# No PyPI token is used in the publish path. The full test suite is intentionally
+# NOT a gate here (that lives in ci.yml on PRs); a tagged release only needs to
+# build cleanly and pass `twine check`, so a red/flaky unrelated test never blocks
+# a release again.
+concurrency:
+  # Never let two releases race: a second push to main waits rather than
+  # computing the same "next" tag from a stale view of the tag list.
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # ---------------------------------------------------------------------- #
+  # Cut the release tag. Only on a push to main; skipped on a tag push.
+  # ---------------------------------------------------------------------- #
+  tag:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      tagged: ${{ steps.bump.outputs.tagged }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history + tags, or `git describe` cannot see the latest tag and
+          # every run would compute v0.0.1.
+          fetch-depth: 0
+          fetch-tags: true
+      - id: bump
+        name: Cut the next patch tag if HEAD is not already tagged
+        run: |
+          set -euo pipefail
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          latest="$(git describe --tags --abbrev=0 --match 'v[0-9]*' 2>/dev/null || echo '')"
+          head_sha="$(git rev-parse HEAD)"
+
+          if [ -n "$latest" ] && [ "$(git rev-list -n1 "$latest")" = "$head_sha" ]; then
+            echo "HEAD is already $latest; nothing to release."
+            echo "tagged=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          base="${latest:-v0.0.0}"
+          ver="${base#v}"
+          IFS='.' read -r major minor patch <<< "$ver"
+          major="${major:-0}"; minor="${minor:-0}"; patch="${patch:-0}"
+          next="v${major}.${minor}.$((patch + 1))"
+          while git rev-parse -q --verify "refs/tags/$next" >/dev/null 2>&1; do
+            patch=$((patch + 1))
+            next="v${major}.${minor}.$((patch + 1))"
+          done
+
+          echo "Cutting $next at ${head_sha:0:8} (previous: ${latest:-none})"
+          git tag -a "$next" -m "release: $next from main"
+          git push origin "$next"
+          echo "tagged=true" >> "$GITHUB_OUTPUT"
+
+  build:
+    needs: [tag]
+    # `always()` is required because `needs` on a SKIPPED job would otherwise
+    # skip this one on the tag-push path.
+    if: >-
+      always() && !cancelled() &&
+      (needs.tag.result == 'skipped' || needs.tag.outputs.tagged == 'true')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm derives the version from the tag, so the tag the job
+          # above just pushed must be visible here or the build would produce a
+          # dev version with a local segment (+g<sha>), which PyPI rejects.
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Refuse to publish a tag that is not on main
+        # The local pre-push hook is a symlink into each clone's working tree, so
+        # a clone that has not pulled the main-only fix keeps cutting tags at
+        # feature-branch tips and pushing them. This is the server-side backstop:
+        # it holds no matter what any developer's clone does.
+        #
+        # Override with the ALLOW_OFF_MAIN_RELEASE repository variable if a
+        # release ever legitimately needs to come off a maintenance branch.
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          set -euo pipefail
+          if [ "${{ vars.ALLOW_OFF_MAIN_RELEASE }}" = "1" ]; then
+            echo "ALLOW_OFF_MAIN_RELEASE=1 is set; skipping the on-main check."
+            exit 0
+          fi
+          git fetch --no-tags origin main:refs/remotes/origin/main
+          if git merge-base --is-ancestor "$GITHUB_SHA" refs/remotes/origin/main; then
+            echo "OK: ${GITHUB_REF_NAME} (${GITHUB_SHA:0:8}) is on main."
+            exit 0
+          fi
+          echo "::error::${GITHUB_REF_NAME} points at ${GITHUB_SHA:0:8}, which is NOT on main. Refusing to publish."
+          echo "::error::A tag cut off a feature branch must not become a release. Delete the tag, merge to main, and let the main push cut the release."
+          exit 1
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi-publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

skcomms-0.2.4/.github/workflows/pytest.yml

@@ -0,0 +1,127 @@
+name: pytest
+
+# Runs the skcomms pytest suite on GitHub-hosted runners.
+#
+# GREEN-by-construction: this mirrors the repo's own known-passing invocation
+# (see qa.yml) — install the package with its `dev` extras, then run the WHOLE
+# suite. The suite is CI-clean: it requires no live external services and no
+# sibling sk* packages.
+#
+# Honest notes on scope (verified 2026-06-28):
+#   * There are NO custom pytest markers in this repo (no `integration`,
+#     `e2e_live`, `bunker`, etc. registered or applied). So there is nothing to
+#     exclude with `-m "not ..."` — adding such a filter would be fabricated.
+#   * Optional-transport tests (telegram/discord/webrtc/zeroconf/liboqs) and the
+#     capauth/skcapstone-dependent paths self-skip via pytest.importorskip /
+#     @pytest.mark.skipif when those packages are absent. The `dev` extras
+#     (pytest, pytest-asyncio, fastapi, httpx, pgpy, websockets, cryptography)
+#     are the deliberate known-green dependency set; sibling sk* packages
+#     (capauth, skcapstone, sk-pqc) are NOT installed and the suite stays green
+#     without them.
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm derives the version from the git tag, so a
+          # shallow checkout would yield a placeholder like 0.1.dev1 and
+          # break dependency resolution against pinned siblings.
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install skcomms + dev extras
+        # -c constraints.txt pins the dev/runtime set to the versions this repo
+        # validated, so a fresh runner installs exactly what CI last tested.
+        run: |
+          python -m pip install --upgrade pip
+          pip install -c constraints.txt -e ".[crypto,dev,pqc]"
+      # skcomms does NOT depend on skcapstone (that would invert the direction),
+      # but tests/test_integration.py exercises "integrated" mode and assumed a
+      # dev venv where skcapstone happens to be installed. In CI it is not, so
+      # those tests errored with ModuleNotFoundError instead of testing anything.
+      # skcoord is named too (skcapstone.coordination is a re-export shim over it),
+      # and skcot, which backs geo_store.SkcotGeoStore and is git-only (not on PyPI,
+      # not declared), so CI could never have exercised the skcot bridge. --no-deps
+      # also stops this dragging a published skcomms over the checkout under test.
+      - name: Install skcapstone (optional integration backbone) from source
+        run: |
+          pip install --no-deps --no-cache-dir \
+            "skcapstone @ git+https://github.com/smilinTux/skcapstone" \
+            "skcoord @ git+https://github.com/smilinTux/skcoord" \
+            "skcot @ git+https://github.com/smilinTux/skcot" \
+            "capauth @ git+https://github.com/smilinTux/capauth"
+      - name: Run pytest (full suite)
+        run: python -m pytest tests/ -q
+
+  # The pqdm/pqdm2 crypto gates are the ONE place a wire-format drift between
+  # this repo and the Dart client (sk-pqc-dart / skworld-app) gets caught, and
+  # they are exactly the tests the `dev`-extras job above cannot run: every
+  # hybrid KEM op needs liboqs, and pqdm.open_multi() swallows a missing backend
+  # into a plain `None` return, so without liboqs the gate cannot fail-loud — it
+  # self-skips. This job installs the `pqc` extra so the gate genuinely runs.
+  #
+  # liboqs-python builds liboqs from source into ~/_oqs on first import when it
+  # cannot find a system copy, so that directory is cached across runs.
+  pqc-interop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm derives the version from the git tag, so a
+          # shallow checkout would yield a placeholder like 0.1.dev1 and
+          # break dependency resolution against pinned siblings.
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Cache the liboqs build
+        uses: actions/cache@v4
+        with:
+          path: ~/_oqs
+          key: liboqs-${{ runner.os }}-${{ hashFiles('constraints.txt') }}
+      - name: Install skcomms + dev + pqc extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -c constraints.txt -e ".[crypto,dev,pqc]"
+      # skcomms does NOT depend on skcapstone (that would invert the direction),
+      # but tests/test_integration.py exercises "integrated" mode and assumed a
+      # dev venv where skcapstone happens to be installed. In CI it is not, so
+      # those tests errored with ModuleNotFoundError instead of testing anything.
+      # skcoord is named too (skcapstone.coordination is a re-export shim over it),
+      # and skcot, which backs geo_store.SkcotGeoStore and is git-only (not on PyPI,
+      # not declared), so CI could never have exercised the skcot bridge. --no-deps
+      # also stops this dragging a published skcomms over the checkout under test.
+      - name: Install skcapstone (optional integration backbone) from source
+        run: |
+          pip install --no-deps --no-cache-dir \
+            "skcapstone @ git+https://github.com/smilinTux/skcapstone" \
+            "skcoord @ git+https://github.com/smilinTux/skcoord" \
+            "skcot @ git+https://github.com/smilinTux/skcot" \
+            "capauth @ git+https://github.com/smilinTux/capauth"
+      - name: Assert the PQ backend is really present
+        # Without this the crypto gates would silently self-skip and the job
+        # would report green while proving nothing.
+        run: |
+          python -c "from skcomms import pqkem; assert pqkem.is_available(), 'liboqs missing: the pqdm gates would self-skip'"
+      - name: Run the pqdm / pqdm2 interop gates
+        run: python -m pytest tests/test_pqdm.py tests/test_pqdm2.py tests/test_pqdm2_interop.py -q

skcomms-0.2.4/.github/workflows/qa.yml

@@ -0,0 +1,55 @@
+name: QA
+
+# Runs the full skcomms QA pytest suite on every push to main, every PR, and
+# every version tag. The suite is CI-clean (no live external services required),
+# so we run it whole.
+
+on:
+  push:
+    branches: ["main"]
+    tags: ["v*"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  qa:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm derives the version from the git tag, so a
+          # shallow checkout would yield a placeholder like 0.1.dev1 and
+          # break dependency resolution against pinned siblings.
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package + dev deps
+        # -c constraints.txt pins to the versions this repo validated (inert on
+        # the fallback branch, which installs a smaller set).
+        run: |
+          pip install -c constraints.txt -e ".[crypto,dev,pqc]" || { pip install -c constraints.txt -e . && pip install -c constraints.txt pytest pytest-asyncio; }
+      # skcomms does NOT depend on skcapstone (that would invert the direction),
+      # but tests/test_integration.py exercises "integrated" mode and assumed a
+      # dev venv where skcapstone happens to be installed. In CI it is not, so
+      # those tests errored with ModuleNotFoundError instead of testing anything.
+      # skcoord is named too (skcapstone.coordination is a re-export shim over it),
+      # and skcot, which backs geo_store.SkcotGeoStore and is git-only (not on PyPI,
+      # not declared), so CI could never have exercised the skcot bridge. --no-deps
+      # also stops this dragging a published skcomms over the checkout under test.
+      - name: Install skcapstone (optional integration backbone) from source
+        run: |
+          pip install --no-deps --no-cache-dir \
+            "skcapstone @ git+https://github.com/smilinTux/skcapstone" \
+            "skcoord @ git+https://github.com/smilinTux/skcoord" \
+            "skcot @ git+https://github.com/smilinTux/skcot" \
+            "capauth @ git+https://github.com/smilinTux/capauth"
+      - name: Run QA pytest suite
+        run: python -m pytest tests/ -q

skcomms-0.2.4/.github/workflows/secret-scan.yml

@@ -0,0 +1,48 @@
+name: secret-scan
+
+# Secret-scan gate: keeps the repo's clean secrets hygiene true over time.
+#
+# Runs gitleaks (the fleet default, via its official GitHub Action) on every
+# push and every pull request. The build FAILS if gitleaks finds anything not
+# covered by the baseline allowlist in .gitleaks.toml at the repo root.
+#
+# The allowlist documents known non-secret placeholder tokens; see that file
+# for how to add an entry when a real placeholder trips the scanner. If the
+# scanner flags a REAL secret, rotate it and purge it from history, do NOT
+# add it to the allowlist.
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  gitleaks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history so a push scans every new commit, not just the tip.
+          fetch-depth: 0
+      - name: Run gitleaks
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          # Use the baseline/allowlist committed at the repo root.
+          GITLEAKS_CONFIG: ${{ github.workspace }}/.gitleaks.toml
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # gitleaks-action requires a license for ORGANIZATION-owned repos.
+          # The note here used to say this repo ran on an individual account;
+          # it does not, it is owned by the smilinTux org, which is why every
+          # run fails with "missing gitleaks license" before scanning anything.
+          # Licensing keys on org-vs-personal, not public-vs-private, so being
+          # a public repo does not exempt it.
+          #
+          # Free key for open source at https://gitleaks.io; add it as an
+          # organization secret named GITLEAKS_LICENSE so every smilinTux repo
+          # can use the same one. Until it exists this reference is harmless:
+          # an unset secret expands to empty, exactly as today.
+          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

skcomms-0.2.4/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg
+.eggs/
+.coverage
+htmlcov/
+MANIFEST.in

skcomms-0.2.4/.gitleaks.toml

@@ -0,0 +1,35 @@
+# gitleaks configuration for skcomms
+#
+# This is the baseline/allowlist that pairs with the secret-scan CI gate
+# (.github/workflows/secret-scan.yml). It keeps the full set of gitleaks
+# default rules and layers on an allowlist for known, non-secret placeholder
+# tokens so the build only fails on genuine findings.
+#
+# How to use it:
+#   * The CI gate (gitleaks GitHub Action) reads this file automatically because
+#     it lives at the repo root and is named .gitleaks.toml.
+#   * To scan locally the same way CI does:
+#       docker run --rm -v "$(pwd):/repo" zricethezav/gitleaks:latest \
+#         detect --source /repo -c /repo/.gitleaks.toml -v
+#   * If gitleaks flags a value that is a documented placeholder or fixture
+#     (not a real secret), add it below with a justification comment. If it
+#     flags a REAL secret, rotate it and purge it from history; do NOT allowlist.
+
+title = "skcomms gitleaks config"
+
+# Start from the full gitleaks default ruleset, then extend with the allowlist
+# below. Without this, only our custom rules would run.
+[extend]
+useDefault = true
+
+# Global allowlists apply to every rule.
+[[allowlists]]
+description = """
+Prose token "Ed25519-signed" in the BLE mesh proximity transport design spec.
+The generic-api-key rule flags the hyphenated cryptography term (high entropy)
+even though it is plain documentation text describing that packets are signed
+with Ed25519, not a credential. Confirmed non-secret on 2026-07-10 by reading
+docs/superpowers/specs/2026-06-13-ble-mesh-proximity-transport-design.md:178.
+"""
+paths = ['''docs/superpowers/specs/2026-06-13-ble-mesh-proximity-transport-design\.md''']
+regexes = ['''Ed25519-signed''']