nfse-br 0.1.0__tar.gz

nfse_br-0.1.0/.gitattributes

@@ -0,0 +1 @@
+contracts/restricted/*.json text eol=lf

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

@@ -0,0 +1,133 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.12"
+          - "3.13"
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          version: "0.12.13"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen --extra xsd
+
+      - name: Lint
+        run: uv run --frozen --extra xsd ruff check .
+
+      - name: Check formatting
+        run: uv run --frozen --extra xsd ruff format --check .
+
+      - name: Type-check
+        run: uv run --frozen --extra xsd mypy src tests scripts examples
+
+      - name: Test
+        run: |
+          mkdir -p build/coverage
+          uv run --frozen --extra xsd pytest \
+            --cov=src/nfse_br \
+            --cov-branch \
+            --cov-report=term-missing \
+            --cov-report=json:build/coverage/coverage.json \
+            --cov-fail-under=80
+
+      - name: Enforce coverage gates
+        run: >-
+          uv run --frozen --extra xsd python scripts/check_coverage.py
+          build/coverage/coverage.json
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Smoke-test base wheel without XSD dependencies
+        run: python scripts/smoke_base_wheel.py dist/nfse_br-0.1.0-py3-none-any.whl
+
+  windows-compatibility:
+    name: windows-compatibility (${{ matrix.python-version }})
+    runs-on: windows-2022
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.12"
+          - "3.13"
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          version: "0.12.13"
+          enable-cache: true
+
+      - name: Confirm Windows runner
+        run: python -c "import os; assert os.name == 'nt'; print(os.name)"
+
+      - name: Install dependencies
+        run: uv sync --frozen --extra xsd
+
+      - name: Lint
+        run: uv run --frozen --extra xsd ruff check .
+
+      - name: Check formatting
+        run: uv run --frozen --extra xsd ruff format --check .
+
+      - name: Type-check
+        run: uv run --frozen --extra xsd mypy src tests scripts examples
+
+      - name: Prepare coverage directory
+        shell: pwsh
+        run: New-Item -ItemType Directory -Force build/coverage | Out-Null
+
+      - name: Test
+        shell: pwsh
+        run: |
+          uv run --frozen --extra xsd pytest `
+            --cov=src/nfse_br `
+            --cov-branch `
+            --cov-report=term-missing `
+            --cov-report=json:build/coverage/coverage.json `
+            --cov-fail-under=80
+
+      - name: Enforce coverage gates
+        run: uv run --frozen --extra xsd python scripts/check_coverage.py build/coverage/coverage.json
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Smoke-test base wheel without XSD dependencies
+        run: python scripts/smoke_base_wheel.py dist/nfse_br-0.1.0-py3-none-any.whl

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

@@ -0,0 +1,184 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions: {}
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          version: "0.12.13"
+          enable-cache: true
+
+      - name: Validate release identity
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          test "$GITHUB_REPOSITORY" = "cassao29/nfse-br"
+          test "$GITHUB_REF_TYPE" = "tag"
+          git fetch origin main --no-tags
+          test "$(git rev-parse 'origin/main^{commit}')" = "$GITHUB_SHA"
+
+          python - <<'PY'
+          from __future__ import annotations
+
+          import ast
+          import os
+          import re
+          import tomllib
+          from pathlib import Path
+
+          tag = os.environ["GITHUB_REF_NAME"]
+          match = re.fullmatch(r"v([0-9]+)\.([0-9]+)\.([0-9]+)", tag)
+          if match is None:
+              raise SystemExit("release tag must match vMAJOR.MINOR.PATCH")
+          version = tag[1:]
+
+          with Path("pyproject.toml").open("rb") as stream:
+              project_version = tomllib.load(stream)["project"]["version"]
+
+          module = ast.parse(
+              Path("src/nfse_br/__init__.py").read_text(encoding="utf-8")
+          )
+          package_versions = []
+          for node in module.body:
+              if (
+                  isinstance(node, (ast.Assign, ast.AnnAssign))
+                  and isinstance(node.value, ast.Constant)
+                  and isinstance(node.value.value, str)
+              ):
+                  targets = (
+                      node.targets if isinstance(node, ast.Assign) else [node.target]
+                  )
+                  if any(
+                      isinstance(target, ast.Name)
+                      and target.id == "__version__"
+                      for target in targets
+                  ):
+                      package_versions.append(node.value.value)
+
+          if package_versions != [version] or project_version != version:
+              raise SystemExit("tag, project version, and package version differ")
+
+          github_env = Path(os.environ["GITHUB_ENV"])
+          with github_env.open("a", encoding="utf-8") as stream:
+              stream.write(f"VERSION={version}\n")
+          PY
+
+      - name: Install frozen environment
+        run: uv sync --frozen
+
+      - name: Build distributions
+        shell: bash
+        run: |
+          set -euo pipefail
+          uv build
+
+          # uv 0.12.13 creates this ignored marker in a new output directory.
+          test "$(cat dist/.gitignore)" = "*"
+          rm -- dist/.gitignore
+
+      - name: Inspect distributions
+        shell: bash
+        run: |
+          set -euo pipefail
+          wheel="dist/nfse_br-${VERSION}-py3-none-any.whl"
+          sdist="dist/nfse_br-${VERSION}.tar.gz"
+
+          test -f "$wheel"
+          test ! -L "$wheel"
+          test -f "$sdist"
+          test ! -L "$sdist"
+
+          shopt -s nullglob dotglob
+          files=(dist/*)
+          test "${#files[@]}" -eq 2
+          test "${files[0]}" = "$sdist" || test "${files[0]}" = "$wheel"
+          test "${files[1]}" = "$sdist" || test "${files[1]}" = "$wheel"
+
+          sha256sum -- "$wheel" "$sdist"
+
+      - name: Smoke-test base wheel
+        shell: bash
+        run: >-
+          python scripts/smoke_base_wheel.py
+          "dist/nfse_br-${VERSION}-py3-none-any.whl"
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      actions: read
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Inspect downloaded distributions
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [[ ! "$GITHUB_REF_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "release tag must match vMAJOR.MINOR.PATCH" >&2
+            exit 1
+          fi
+          version="${GITHUB_REF_NAME#v}"
+          wheel="dist/nfse_br-${version}-py3-none-any.whl"
+          sdist="dist/nfse_br-${version}.tar.gz"
+
+          test -f "$wheel"
+          test ! -L "$wheel"
+          test -f "$sdist"
+          test ! -L "$sdist"
+
+          shopt -s nullglob dotglob
+          files=(dist/*)
+          test "${#files[@]}" -eq 2
+          test "${files[0]}" = "$sdist" || test "${files[0]}" = "$wheel"
+          test "${files[1]}" = "$sdist" || test "${files[1]}" = "$wheel"
+
+          sha256sum -- "$wheel" "$sdist"
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/
+          attestations: true
+          skip-existing: false

nfse_br-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+
+# Test and coverage artifacts
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Type-checker and linter caches
+.mypy_cache/
+.ruff_cache/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# IDE and editor files
+.idea/
+.vscode/
+*.swp
+
+# Local environment and credentials
+.env
+.env.*
+!.env.example
+*.pfx
+*.p12
+*.pem
+*.key
+
+# Local official-contract evidence bytes
+.f0/

nfse_br-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

nfse_br-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+## 0.1.0
+
+### Added
+
+- Typed primitives for NFS-e environment, federal tax identifiers,
+  municipality codes, competence dates, DPS series, DPS numbers, and DPS
+  identity.
+- Explicit, opt-in CPF and numeric/alphanumeric CNPJ check-digit validation.
+- Frozen provenance for the official restricted-environment evidence and a
+  derived restricted DPS schema contract.
+- Local validation against the pinned restricted XSD bundle through the
+  optional `xsd` extra.
+- A deterministic unsigned DPS builder for a deliberately limited restricted
+  subset.
+- A private structural signature preflight that rejects ambiguous targets;
+  this is not signing or cryptographic verification.
+- The `nfse-br check-unsigned` CLI with machine-readable results and bounded
+  file reads.
+- Linux and Windows Server 2022 CI for Python 3.12 and 3.13.
+- A tested executable quickstart for generating a synthetic unsigned DPS from
+  a checkout.
+
+### Security / hardening
+
+- XML parsing denies DTDs, entities, external resolution, unexpected roots,
+  and inputs above the documented size limit.
+- Signature preflight requires one unambiguous direct `infDPS`, rejects
+  competing identifiers and pre-existing signatures, and reconstructs its
+  identity from the document fields.
+- CLI diagnostics use controlled JSON error codes without echoing fiscal
+  payloads or caller-provided paths.
+- Base-wheel smoke tests verify that generation and non-XSD operations remain
+  usable without `lxml`.
+
+### Known limitations
+
+- Issuance, authorization, transmission, HTTP/SEFIN integration, certificate
+  handling, and private-key handling are not implemented.
+- The applicable XMLDSig algorithm profile remains unresolved; signing and
+  cryptographic verification are not implemented.
+- The builder covers only the documented restricted-environment subset, not a
+  complete fiscal model.
+- The production environment is unsupported.
+- End-to-end validation with the pinned official bundle is a local release
+  gate and is not executed in CI by design.

nfse_br-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+This project supports Python 3.12 and 3.13 and uses
+[`uv`](https://docs.astral.sh/uv/) for dependency and environment management.
+
+Use GitHub Flow: branch from an up-to-date `main`, keep pull requests small,
+and use Conventional Commit messages. Do not commit downloaded official
+ZIP/XSD/XLSX/PDF artifacts, generated XML, coverage reports, `.f0/` contents,
+certificates, keys, or fiscal data.
+
+Install the frozen development environment and run the same core checks used
+by CI:
+
+```console
+uv sync --frozen --extra xsd
+uv run --frozen --extra xsd ruff check .
+uv run --frozen --extra xsd ruff format --check .
+uv run --frozen --extra xsd mypy src tests scripts examples
+uv run --frozen --extra xsd coverage erase
+uv run --frozen --extra xsd python -c "from pathlib import Path; Path('build/coverage').mkdir(parents=True, exist_ok=True)"
+uv run --frozen --extra xsd pytest \
+  --cov=src/nfse_br --cov-branch --cov-report=term-missing \
+  --cov-report=json:build/coverage/coverage.json --cov-fail-under=80
+uv run --frozen --extra xsd python scripts/check_coverage.py \
+  build/coverage/coverage.json
+uv build
+uv run --frozen --extra xsd python scripts/smoke_base_wheel.py \
+  dist/nfse_br-0.1.0-py3-none-any.whl
+```
+
+Run the suite under both supported Python versions. Pull requests are checked
+on Linux and Windows Server 2022; platform-specific skips must be narrow and
+justified. Tests are offline unless a documented local integration procedure
+explicitly says otherwise.
+
+Never weaken evidence pins, parser policy, coverage thresholds, or branch
+protection merely to make a change pass.

nfse_br-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cássio Santos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.