fiskalizimi-utils

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

The repository contains the full commit history, not only release drops: https://github.com/square-al/fiskalizimi-utils/commits/main .

Repository on GitHub, which uses git. git is distributed.

Each release has a unique version, currently 0.2.0, carried consistently across package.json, jsr.json, the Python package and the MCP manifest. CI fails the build if the MCP manifest.json and server.json versions do not match package.json.

Semantic Versioning is used, e.g. 0.2.0.

Each release is tagged in git as vX.Y.Z; tagging is what triggers publication. See https://github.com/square-al/fiskalizimi-utils/tags .

Every release has hand-written, human-readable release notes describing what changed and why, grouped by component, not a git log dump. See https://github.com/square-al/fiskalizimi-utils/releases .

There have been no publicly known vulnerabilities in this project, so no release notes have had to identify one. No CVE has ever been assigned against it.

Non-trivial SECURITY[.md] file found file in repository: https://github.com/square-al/fiskalizimi-utils/blob/main/SECURITY.md. [osps_do_02_01]

GitHub Issues is used for tracking individual issues: https://github.com/square-al/fiskalizimi-utils/issues .

No bug reports have been submitted by third parties in the last 2-12 months, so there are none outstanding without acknowledgement. The tracker is monitored by the maintainers and issues opened by the maintainers themselves are worked and closed.

No third-party enhancement requests have been received in the last 2-12 months, so there are none outstanding without a response. The tracker is monitored.

All issues and their responses stay publicly readable and searchable at https://github.com/square-al/fiskalizimi-utils/issues?q=is%3Aissue .

The process is published at https://github.com/square-al/fiskalizimi-utils/blob/main/SECURITY.md and summarised in the README's Security section. It is also consistent with the organisation-wide RFC 9116 contact at https://square.al/.well-known/security.txt and the disclosure policy at https://square.al/en/security-compliance .

Two private channels are documented in https://github.com/square-al/fiskalizimi-utils/blob/main/SECURITY.md : GitHub private vulnerability reporting (enabled on this repository, https://github.com/square-al/fiskalizimi-utils/security/advisories/new ), which keeps the report private until published, and email to info@square.al . Reporters are explicitly asked not to open a public issue.

No vulnerability report has been received in the last 6 months. SECURITY.md commits to an initial response within 14 days and tells reporters to chase info@square.al if they have not heard back in that time.

The TypeScript build is "npm run build" (tsc against tsconfig.build.json). The Python package builds from python/ with standard packaging. Both are rebuilt from source automatically in CI on every push and pull request.

Standard tooling only: npm and the TypeScript compiler for the TypeScript port, standard Python packaging for the Python port, and Docker for the CLI image.

npm, TypeScript, Node.js, Python and Docker are all FLOSS. The project has zero runtime dependencies.

Automated test suites are released as FLOSS in this repository under the same MIT licence: TypeScript tests in src/*.test.ts and Python tests in python/tests/ . How to run them is documented in the README and in CONTRIBUTING.md, and they are run on every push and pull request by https://github.com/square-al/fiskalizimi-utils/blob/main/.github/workflows/ci.yml .

Standard invocation for each language: "npm test" (node --test) for TypeScript, and "PYTHONPATH=src python -m unittest discover -s tests -t tests" for Python.

Every exported function in both ports has tests: NIPT/NUIS validation, TVSH math, invoice totals, payroll, profit tax, rates lookup and the CLI. The Python suite is 104 tests and includes doctests. A shared parity fixture asserts that the TypeScript and Python implementations return identical results, so a gap in one port is caught by the other. No published coverage percentage is claimed.

https://github.com/square-al/fiskalizimi-utils/blob/main/.github/workflows/ci.yml runs on every push to main and every pull request: TypeScript tests and build, the MCP server build and pack, a Python matrix on 3.10 and 3.13, a strict documentation build, and a check that the generated dataset still matches the library.

The policy is written down in https://github.com/square-al/fiskalizimi-utils/blob/main/CONTRIBUTING.md under "Testing policy": as functionality is added or changed, tests for it are added in the same pull request. It is stated as a hard requirement, and lists what that means for a new function, a bug fix, and a rate change.

The policy has been followed. Each module ships with its own test file alongside it in both ports. The most recent major change, adding payroll and profit tax to the TypeScript port in v0.2.0, shipped with src/payroll.test.ts and with a shared parity fixture asserting the new TypeScript results against the existing Python implementation.

The requirement to add tests in the same pull request is documented in the contribution instructions: https://github.com/square-al/fiskalizimi-utils/blob/main/CONTRIBUTING.md .

TypeScript is compiled in strict mode with "strict": true and "noUncheckedIndexedAccess": true in tsconfig.json, which is the "safe language mode" for this language. The documentation build additionally runs "mkdocs build --strict". CodeQL runs with the security-and-quality query pack, which includes code-quality rules beyond compiler warnings.

Warnings and type errors are treated as build failures rather than logged and ignored: CI runs "npm test" and "npm run build" and the job fails on any TypeScript error, so nothing merges to main with an outstanding warning.

The project is deliberately strict: "strict" plus "noUncheckedIndexedAccess", a strict docs build, a CI check that fails if the generated dataset is stale, and a CI check that fails if the MCP manifest and server versions drift from package.json. CONTRIBUTING.md forbids weakening these or using "any" or "@ts-expect-error" to get a build green.

At least one primary developer applies secure design principles to this project: it is deliberately a set of pure functions with no network calls, no file or environment access, no credentials and no dependencies, which keeps the attack surface minimal and makes the trust boundary explicit (input validation happens at the library edge, and the calling application remains responsible for its own I/O). The maintainers build and operate production systems handling fiscal and payroll data and apply least privilege, input validation and minimal-attack-surface design in that work. The publishing pipeline uses OIDC with no stored long-lived tokens.

The maintainers are familiar with the common error classes relevant to this kind of software and the mitigations used here: untrusted input handling, mitigated by validating NIPT/NUIS format and numeric inputs at the library boundary and by having no parser that touches the network or filesystem; injection, which is out of reach because the library issues no queries, no shell commands and no HTTP requests; denial of service through pathological input, mitigated by bounded, non-recursive arithmetic; numeric correctness errors, which are the realistic failure mode here and are mitigated by exact money handling, dated rates configs and a parity fixture across the two ports; and supply-chain compromise, mitigated by zero runtime dependencies, OIDC-based publishing without stored tokens, and secret scanning with push protection enabled on the repository.

The software implements and uses no cryptography. It is a set of pure arithmetic and validation functions and performs no network communication, no authentication and no signing.

The software performs no cryptographic operations, so it neither calls nor re-implements any cryptographic function.

No functionality in this software depends on cryptography.

The software contains no security mechanism that uses keys.

The software uses no cryptographic algorithms, broken or otherwise.

The software uses no cryptographic algorithms or modes.

The software implements no key agreement protocol and performs no network communication.

The software does not authenticate users and never stores or handles passwords.

The software generates no cryptographic keys or nonces. It contains no random number generation in any security-relevant path.

Distribution channels use HTTPS exclusively. [osps_br_03_02]

No cryptographic hash is retrieved over http and used unverified. The project retrieves nothing at runtime: it has zero runtime dependencies and makes no network calls. Build-time dependencies are fetched by npm and pip over HTTPS with lockfile integrity hashes.

There are no known unpatched vulnerabilities of medium or higher severity in this project. No CVE has been assigned against it and no vulnerability report has been received.

No critical vulnerability has been reported to date. SECURITY.md commits to an initial response within 14 days and to agreeing a fix window with the reporter, and the release process can ship a fix to npm, JSR, PyPI, Docker and the MCP bundle from a single tag.

The repository contains no credentials. Publication to PyPI and JSR uses OIDC with no stored tokens, so there is no long-lived secret to leak. GitHub secret scanning and push protection are both enabled on this repository, which blocks a credential from being pushed in the first place.

CodeQL is applied to every proposed change and therefore to every release: https://github.com/square-al/fiskalizimi-utils/blob/main/.github/workflows/codeql.yml . It analyses both the TypeScript and the Python sources.

The CodeQL workflow uses the "security-and-quality" query pack for both javascript-typescript and python, which includes CodeQL's standard rules for common vulnerabilities in those languages in addition to code-quality rules.

No medium or higher severity exploitable vulnerability has been reported by static analysis to date. Results are delivered to the repository's security tab, and the project policy is to fix any medium or higher finding before the next release.

CodeQL runs on every push to main, on every pull request, and additionally on a weekly schedule so that a newly published query finds existing code without waiting for a commit.

The project produces no software written in a memory-unsafe language. It is TypeScript and Python only, with no native extensions and no FFI.

Both test suites are assertion-based and are run on every push and pull request: node --test for TypeScript and unittest plus doctests for Python, including a parity fixture that asserts the two ports produce identical results.

No dynamic analysis is currently performed, so no vulnerability has been discovered by it.