namespy 0.1.0__tar.gz

namespy-0.1.0/.gitattributes

@@ -0,0 +1,27 @@
+# Line endings are a correctness issue here, not a style one: CI runs the same
+# suite on Ubuntu and Windows, and a checkout that rewrites bytes per platform
+# means the formatter, the tests and the reviewer are looking at different
+# files. The index stores LF; core.autocrlf is a per-machine setting that cannot
+# be relied on to agree, so the policy is declared in the repository instead.
+* text=auto eol=lf
+
+# Shell must stay LF or it will not execute when checked out on Windows and
+# copied into a Linux container.
+*.sh text eol=lf
+
+# Windows files that must keep CRLF to be useful as-is.
+*.bat text eol=crlf
+*.cmd text eol=crlf
+
+# Never run end-of-line conversion or diff over these.
+*.png binary
+*.jpg binary
+*.gif binary
+*.ico binary
+*.sqlite binary
+*.db binary
+*.pdf binary
+
+# The root hints file is data with an exact on-the-wire meaning per RFC 1035
+# section 5; keep its LF and treat edits to it as substantive.
+namespy/named.root text eol=lf

namespy-0.1.0/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,73 @@
+name: Bug report
+description: A crash, a wrong answer, or a divergence from a DNS specification
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        DNS bugs are usually invisible without the bytes. If something parsed
+        wrong, crashed, or produced an unexpected answer, **include the packet**
+        as a hex string — that single thing decides whether the report is
+        actionable.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Which part?
+      options:
+        - Wire parsing (a crash or a wrong decode)
+        - Resolver behaviour (referrals, caching, aliases, glue)
+        - Server (`--serve`)
+        - CLI output
+        - Packaging / install
+        - Something else
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened, and what did you expect?
+      description: >
+        For a parsing bug, paste the datagram as hex (`data.hex()`), plus the
+        offset in the error if one was raised. For a resolver bug, `namespy
+        --trace NAME` and the resulting `last_resolution.md` are usually enough
+        on their own.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Shortest reproduction
+      description: >
+        A few lines that show it, run against a clean checkout. Please prefer
+        `pip install -e ".[dev]"` at the commit you tested over a released
+        version, since this repository is not on PyPI.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: spec
+    attributes:
+      label: Specification
+      description: >
+        If you know which section this violates, cite it — e.g. "RFC 9267
+        section 5: RDLENGTH must be checked before the RDATA is read". If you do
+        not know, leave this empty and say so; guessing is still useful.
+      placeholder: RFC nnnn section n.n
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version, and whether you ran with `-O` / `PYTHONOPTIMIZE`
+      placeholder: Windows 11, Python 3.12.7, no -O
+    validations:
+      required: true
+  - type: checkboxes
+    id: gates
+    attributes:
+      label: Checked the local gates?
+      description: These are the exact commands CI runs, so failing them here saves a round trip.
+      options:
+        - label: "`pytest -q` passes on a clean checkout"
+        - label: "`python -O -m pytest -q` also passes (assertions stripped)"
+        - label: "`ruff check .` and `mypy namespy` are clean"

namespy-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security issue
+    url: https://github.com/b1tninja/namespy/security/advisories/new
+    about: >
+      Parser and resolver bugs are often remotely reachable from one malformed
+      datagram. Please use a private advisory, not a public issue — see
+      SECURITY.md.
+  - name: Spec and design questions
+    url: https://github.com/b1tninja/namespy/discussions
+    about: >
+      "Should this reject or tolerate that label?" and similar questions are
+      about which RFC reading we adopt. docs/rfc-map.md records the current
+      reading; a discussion is the right place to argue with it.

namespy-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,48 @@
+<!--
+Delete any section that genuinely does not apply, but keep the gate list.
+-->
+
+## What problem does this solve?
+
+One or two sentences. If it fixes an issue, link it.
+
+## Behaviour change?
+
+Say so explicitly if any of these moved, and update `CHANGELOG.md` under
+Unreleased:
+
+- [ ] A packet that used to parse now raises (or the reverse)
+- [ ] A TTL, cache, or negative-answer decision changed
+- [ ] A public name changed (module, class, enum member, CLI flag)
+- [ ] Nothing observable changed
+
+A parser that starts rejecting input is a *feature* here if the input was
+malformed — RFC 5625 section 6.3 permits dropping a broken message and does not
+require tolerating it. But it must be a decision, not a surprise.
+
+## Gates
+
+These are the commands CI runs. Run them locally before pushing; the `-O` run is
+the one that catches assertions carrying real validation, which is this codebase's
+main historical failure mode.
+
+```bash
+pytest -q                      # coverage floor enforced by pyproject
+python -O -m pytest -q
+ruff check . && ruff format --check .
+mypy namespy
+```
+
+- [ ] All four pass locally
+
+## Spec
+
+Which document and section required this? If the change *is* a spec question, the
+reading you chose belongs in `docs/rfc-map.md` — that file exists so the next
+person does not have to re-litigate it.
+
+## Tests
+
+Every parser change needs a byte-level test that pins the exact failure, not just
+a round-trip. For a new rejection, name the condition in the test. For a new
+acceptance, assert the decoded value, not merely that nothing raised.

namespy-0.1.0/.github/dependabot.yml

@@ -0,0 +1,34 @@
+version: 2
+updates:
+  # Only the dev extra resolves here -- the library itself declares no runtime
+  # dependencies, which is a deliberate property of this codebase rather than an
+  # oversight. Keeping the toolchain fresh is still worth a pull request, because
+  # a stale ruff or pytest is what makes CI disagree with a local run.
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "deps"
+    groups:
+      # One PR for the test/lint toolchain instead of five, since they are
+      # upgraded together or not at all.
+      dev-toolchain:
+        patterns:
+          - "pytest*"
+          - "ruff"
+          - "mypy"
+          - "hypothesis"
+          - "build"
+
+  # The actions themselves are third-party code executing with a repository
+  # token, so their pins get the same review as dependencies.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    commit-message:
+      prefix: "ci"

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

@@ -0,0 +1,155 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Hypothesis writes its counterexample database into the repo, which on a
+  # shared runner means a failure reproduced locally never reaches CI. Cached
+  # explicitly below instead of being thrown away with the rest of the checkout.
+  HYPOTHESIS_STORAGE_DIRECTORY: .hypothesis
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: python -m pip install --upgrade pip && pip install -e ".[dev]"
+
+      # `check` reports, `format --check` is the one that notices drift: a
+      # formatter that only runs on a developer's machine diverges silently and
+      # then produces whole-file diffs in the next unrelated commit.
+      - run: ruff check . --output-format=github
+      - run: ruff format --check .
+
+      # Blocking at the level the code is actually at: mypy namespy exits 0 today,
+      # so a check that merely printed the count would let regressions through
+      # while looking like a gate. --strict measures 274 errors, and 245 of them
+      # are no-untyped-def plus no-untyped-call -- one root cause, functions with
+      # no annotations, concentrated in resolver.py (132) rather than spread
+      # evenly. That is a per-module campaign, not a flag to flip: enabling
+      # strict globally would mean silencing the result, which is how a type
+      # checker stops being read.
+      - run: mypy namespy
+
+  # The optional backends, exercised where they exist. The Test matrix runs
+  # without a crypto backend -- that is the configuration most people install, and the
+  # no-backend path is what must stay clean -- so without this job the [crypto] extra
+  # would ship untested and the integration points its transports rest on would be
+  # assumptions. The [doh] extra (pure Python, no wheels to advise against) does ride
+  # the matrix, because an optional transport the matrix cannot run is a transport the
+  # matrix cannot cover either: the TLS fixtures are static stdlib material, so with
+  # h2 present every DoT and DoH line is exercised in all four matrix jobs -- and the
+  # coverage floor is the proof: when the dot/doh tests skipped for lack of a
+  # certificate generator, doh.py measured 15% and the floor broke the commit.
+  crypto_extra:
+    name: Crypto extra
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+      # Resolving the extras is itself the check: it fails if a floor cannot be satisfied
+      # by a wheel on a supported platform, which is the failure mode an optional
+      # dependency has that no unit test can see.
+      - run: python -m pip install --upgrade pip && pip install -e ".[dev,crypto,doh]"
+      - run: python -c "import cryptography, namespy.crypto as c; b=c.require_backend('probe'); print(b.name, b.version)"
+      - run: python -m pytest -q tests/test_crypto_backend.py
+      - run: python -c "import h2, namespy.doh as d; assert d.H2_AVAILABLE; print('h2', h2.__version__)"
+      - run: python -m pytest -q tests/test_stub_doh.py
+
+  test:
+    name: Test py${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Windows is not decoration. The bundled server used to call
+        # setsockopt(IPPROTO_IP, IP_MTU_DISCOVER, ...) unconditionally with
+        # hardcoded Linux constants, which raised on Windows in connection_made
+        # -- a bug that no Linux-only CI could ever see. asyncio also swaps to
+        # ProactorEventLoop here, so socket lifetime differs by platform.
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install --upgrade pip && pip install -e ".[dev,doh]"
+
+      # The coverage floor is fail_under in pyproject.toml, not duplicated here,
+      # so the threshold and the explanation for it stay in one file. The --cov
+      # flag is what makes pytest read that file: pytest-cov measures only when
+      # asked, so this step exited 0 whatever the tests covered and the floor was
+      # decoration: the floor (50012b4) and the CI that never asked for a
+      # measurement (ecedb5c) both landed 2026-10-27. Checked both ways: one test
+      # file now exits 1 with "Required test coverage of 80.0% not reached", the
+      # whole suite exits 0 at 87%.
+      - name: pytest
+        run: python -m pytest -q --cov
+
+      # This step is the reason the suite is worth running at all here. Every
+      # bounds check on a wire path was once an `assert`, which python -O strips
+      # out of the bytecode; the parser's hardening is therefore only real if the
+      # hostile-input tests still pass with assertions compiled away. Without
+      # this leg, "no assert on network data" is a comment rather than a policy.
+      - name: pytest under -O (assertions stripped)
+        run: python -O -m pytest -q -p no:cacheprovider
+
+      - uses: actions/upload-artifact@v7
+        if: failure()
+        with:
+          name: pytest-${{ matrix.os }}-py${{ matrix.python-version }}
+          path: |
+            .hypothesis/
+            last_resolution.md
+          if-no-files-found: ignore
+
+  dist:
+    name: Build and audit distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: python -m pip install --upgrade pip && pip install -e ".[dev]"
+      - run: python -m build
+      - run: python tools/check_dist.py dist/
+      # Installs the wheel in a clean venv and asserts the root hints arrive
+      # through importlib.resources -- the one failure mode unit tests cannot
+      # see, because they always run against the source tree.
+      #
+      # The `cd /` is load-bearing: the checkout contains an namespy/ directory,
+      # so importing from the workspace would silently import the source tree and
+      # "pass" no matter what the wheel actually contains.
+      - name: Install the wheel and load hints from it
+        run: |
+          python -m venv /tmp/verify
+          /tmp/verify/bin/python -m pip install --no-deps dist/*.whl
+          cd /
+          /tmp/verify/bin/python -c "import namespy, importlib.resources as r; print(len(r.files('namespy').joinpath('named.root').read_text().splitlines()), 'root hint lines')"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/

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

@@ -0,0 +1,152 @@
+name: Release
+
+# Publishing is deliberately tag-gated rather than push-to-master: this project
+# has never been on PyPI, and the first upload should be an explicit act with a
+# version that exists in the tree. Cut a release with:
+#
+#   git tag v0.1.0 && git push origin v0.1.0
+#
+# The tag must agree with namespy.__init__.__version__, which is what hatchling
+# reads for the wheel's own version -- an unforced mismatch would put a name on
+# PyPI that no source tree anywhere claims to be.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release this version; must equal namespy.__version__ (e.g. 0.1.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build release artifacts
+    runs-on: ubuntu-latest
+    # id-token + attestations are for the provenance step below; everything
+    # else in this job stays under contents: read.
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+      artifact-metadata: write
+    outputs:
+      digest: ${{ steps.hash.outputs.digest }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: python -m pip install --upgrade pip && pip install -e ".[dev]"
+
+      - name: Refuse a version that disagrees with the package
+        env:
+          # Passed through the environment rather than interpolated into the
+          # script: an input is data, not shell text, even a maintainer's.
+          INPUT_VERSION: ${{ inputs.version }}
+        run: |
+          # A dispatched run carries no tag, so GITHUB_REF_NAME would be a
+          # branch name and the comparison would always fail; the input stands
+          # in for the tag. The rule itself is the same either way: what lands
+          # on PyPI must be a version some source tree actually claims.
+          if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ]; then
+            WANT="${INPUT_VERSION}"
+          else
+            WANT="${GITHUB_REF_NAME#v}"
+          fi
+          ACTUAL="$(python -c 'import namespy; print(namespy.__version__)')"
+          if [ "$WANT" != "$ACTUAL" ]; then
+            echo "release says $WANT but namespy.__version__ is $ACTUAL" >&2
+            exit 1
+          fi
+
+      - run: python -m build
+      - run: python tools/check_dist.py dist/
+
+      # GitHub-side SLSA provenance, signed by Sigstore against this run's OIDC
+      # identity: `gh attestation verify` ties the shipped files back to this
+      # repo and commit. PyPI receives its own PEP 740 attestations from the
+      # publish action; two independent proofs of the same build.
+      - name: Attest build provenance
+        uses: actions/attest@v4
+        with:
+          subject-path: dist/*
+
+      # SLSA provenance attribute: the SHA256 of every artifact the publish job
+      # will upload. Recorded here so a later audit can tie a file on PyPI back
+      # to this exact run without trusting the PyPI entry.
+      - name: Collect artifact digests
+        id: hash
+        run: |
+          cd dist && LANG=C LC_ALL=C sha256sum * | sort | sed 's/ *  */ /' \
+            | base64 -w0 > ../digest.b64
+          echo "digest=$(cat ../digest.b64)" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: release-dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Trusted publishing (OIDC) rather than a stored API token: no long-lived
+    # credential exists to leak, and the audience/environment gate means only
+    # this repository's tagged builds can mint an upload credential.
+    #
+    # The `pypi` environment exists in Settings -> Environments; the job
+    # names it, so only runs from this repo/workflow can mint its token.
+    # The remaining half is on PyPI: the project `namespy` must list this
+    # repo, this workflow file and this environment name as a trusted
+    # publisher before any upload will be accepted. Until then a misfired
+    # tag fails at `twine` with a legible OIDC error rather than publishing.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/namespy
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: release-dist
+          path: dist/
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      - run: python -m pip install --upgrade twine
+      - run: python -m twine check dist/*
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          print-hash: true
+          # PEP 740 digital attestations are generated and uploaded by the
+          # action automatically for trusted publishing; there is nothing to
+          # enable here.
+
+  release:
+    name: Create the GitHub Release
+    needs: [build, publish]
+    # A dispatched run has no tag to cut a release from: it is a rehearsal of
+    # the build/publish path and stays out of the releases list.
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: release-dist
+          path: dist/
+      # The GitHub Release is the human-facing artifact page, and it only
+      # appears after PyPI accepted the files: a failed publish leaves no
+      # half-release pointing at binaries that are not on PyPI.
+      - name: Publish the release
+        run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+

namespy-0.1.0/.github/workflows/security.yml

@@ -0,0 +1,78 @@
+name: Security
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  schedule:
+    # Weekly even without pushes, so a new CodeQL rule or a newly disclosed
+    # advisory surfaces against this code. Push-triggered analysis only ever
+    # asks about today's code with today's tools.
+    - cron: "17 3 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  codeql:
+    name: CodeQL (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 360
+    permissions:
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        # Only Python source here ships logic; the workflow files themselves
+        # are covered by review + Dependabot, not by a query pack.
+        language: [python]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      - uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          # security-extended over security-and-quality: this is a parser
+          # library whose real risk is hostile input, and the extended pack is
+          # the one that queries for it. The quality queries are already
+          # ruff's job and are enforced in ci.yml.
+          queries: security-extended
+      - uses: github/codeql-action/autobuild@v4
+      - uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"
+
+  dependency-review:
+    # Diff-aware: it flags a newly *introduced* dependency on the PR that
+    # adds it, which no post-merge scanner does at the moment it matters.
+    # Only meaningful on pull_request, where there is a base to diff against.
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/dependency-review-action@v5
+        with:
+          fail-on-severity: high
+          comment-summary-in-pr: always
+
+  pip-audit:
+    # Audits the fully resolved dev-extra environment against the PyPA
+    # advisory DB. The library itself declares zero runtime dependencies, so
+    # what this can actually catch lives in the toolchain that builds, tests
+    # and publishes it -- which is where a Python supply-chain attack lands.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: python -m pip install --upgrade pip && pip install -e ".[dev]" pip-audit
+      - run: python -m pip_audit

namespy-0.1.0/.github/workflows/socket.yml

@@ -0,0 +1,37 @@
+name: Socket
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: socket-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  firewall:
+    name: Screen dependency installs (Socket Firewall)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # setup-python deliberately comes *before* Socket (per Socket's own
+      # ordering guidance) and the pip step deliberately does not use
+      # actions/setup-python's cache: a cached wheel install never talks to
+      # the index, so nothing gets screened and the job would green-light a
+      # compromised release.
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      # Pinned to the immutable tag Socket's own docs recommend; Dependabot
+      # (github-actions ecosystem) keeps it current.
+      - uses: SocketDev/action@v1.3.2
+        with:
+          mode: firewall-free
+      # The point of the job: every dev dependency crosses the firewall on
+      # its way in. The library has no runtime dependencies to screen; the
+      # dev extra is the real attack surface.
+      - run: sfw pip install -e ".[dev]"