ksef_client 0.1.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0e0a3a152f2257ff0f45b86a8027f6a48a8b1ff6612b940284c155bf1a9d6702
+  data.tar.gz: ffed0fa233572a528a77ffdcc0e0171a96f7a755ffff1dfc4561c955b15bc32b
+SHA512:
+  metadata.gz: c3c6068d0d7bbdc5ee4aad882950e13b497da3633b1e832357ae42597952c197734229dab9cd5b7f20680dbb4f3028291e953028fcae3a7ac9fe10a0a9465c7c
+  data.tar.gz: e99942deca0206d28f0919d58ad94bf83c6e9e689868b76e7968518d343ca0ea10fdb47a537a817ba537b7b83137c1ff9b6ba1ba9da89eaab0d8ac22823b9fb9

data/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project are documented here, following
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Every release entry states the **KSeF API version** and **FA schema revision** it
+targets. The Ministry ships changes continuously, so users must be able to answer "which
+gem version for which API state".
+
+## [Unreleased]
+
+## [0.1.0.rc1] — 2026-08-22
+
+**Targets:** KSeF API 2.0 · FA(3) `1-0E` (`kodSystemowy` `FA (3)`, variant 3)
+· upstream `CIRFMF/ksef-api@1c34fe27` (2026-07-21)
+
+> **Prerelease. Not usable for invoicing.** This release exists to verify the trusted
+> publishing pipeline and to claim the gem name. It contains the transport foundations
+> only — authentication, encryption, sessions and the FA(3) builder are not implemented,
+> so no invoice can be sent yet. Prereleases are not installed by `gem install
+> ksef_client`; you would have to ask for this version explicitly.
+
+### Added
+
+- Pinned upstream artifacts with SHA-256 manifest: the OpenAPI 3.0.4 contract
+  (78 paths, 302 schemas) and the FA(3) XSD with its three base schemas. Verified on
+  every test run and by `rake verify:artifacts`.
+- `docs/REFERENCE.md`, the verification ledger — every externally sourced fact with its
+  source URL and retrieval date.
+- `Ksef::Environments` with TEST, DEMO and PROD base URLs verified against each
+  environment's own OpenAPI document, plus a `custom(base_url:)` escape hatch that
+  requires HTTPS.
+- `Ksef::Configuration` — frozen at construction for thread safety, with a redacting
+  `#inspect`, duck-typed logger validation, and rejection of unknown options.
+- `Ksef::RetryPolicy` — idempotent-only retries with capped exponential backoff, honouring
+  `Retry-After` unclamped. Invoice submission is never auto-retried.
+- Full error hierarchy under `Ksef::Error`, including `AuthorizationError` (403, with
+  `reason_code` and the structured `security` payload) and `ResourceGoneError` (410).
+- `Ksef::ProblemDetails` — normalises both KSeF error envelopes (`application/problem+json`
+  and the deprecated `application/json` shapes) and degrades gracefully on non-JSON bodies.
+- `Ksef::HTTP::Connection` — Faraday connection factory with TLS 1.2 floor, verification
+  always on, and error mapping.
+- `Ksef::HTTP::SystemWarning` — surfaces the `X-System-Warning` advisory header the API
+  sets on successful responses.
+- CI: test matrix across Ruby 3.2/3.3/3.4/4.0/head, nightly TEST integration, and a
+  tag-triggered release workflow using RubyGems Trusted Publishing.
+
+### Notes
+
+- The `ksef-docs` repository named in the design document does not exist; all upstream
+  documentation, the OpenAPI spec and the FA schemas live in `CIRFMF/ksef-api`.
+- Endpoint paths carry no `/api` prefix — the base URL includes `/v2` and paths are
+  appended bare.
+- The FA(3) schemas are MIT-licensed by Ministerstwo Finansów, so they are bundled with
+  the gem rather than fetched at first run.
+- **The Ruby 3.2 floor is retained despite 3.2 reaching EOL upstream**, as a deliberate
+  exception to the EOL-drop policy (DESIGN.md §3). The full suite is verified green on
+  3.2.11. The EOL-drop rule governs 3.3 and later series.

data/CONTRIBUTING.md

@@ -0,0 +1,103 @@
+# Contributing
+
+## Getting set up
+
+```bash
+bin/setup            # bundle install + verify pinned artifacts
+bundle exec rake     # verify:artifacts, specs, RuboCop
+```
+
+Development targets the current Ruby 4.0 patch (see `.ruby-version`) because the
+strictest interpreter surfaces un-bundled-stdlib and deprecation issues locally. The
+library itself supports MRI >= 3.2.
+
+## The one rule that matters most
+
+**Never invent an endpoint path, XML element name, namespace URI, or cryptographic
+parameter.**
+
+This gem talks to a tax authority. A plausible-looking guess that happens to be wrong
+produces rejected invoices, or worse, silently malformed ones. So:
+
+1. Every externally sourced fact goes in [`docs/REFERENCE.md`](docs/REFERENCE.md) with its
+   value, source URL and retrieval date, *before* the code depending on it is written.
+2. The authoritative sources, in order: the integrator documentation portal, the
+   `CIRFMF/ksef-api` repository, the pinned OpenAPI spec, the pinned FA(3) XSD.
+3. If a detail is not in the ledger and not verifiable from those sources, **stop and ask**
+   rather than guessing.
+4. When the pinned artifacts and the design document disagree, the artifacts win. Update
+   the ledger and note the divergence in your PR description.
+
+## Pinned artifacts
+
+`spec/fixtures/openapi/open-api.json` and `lib/ksef/fa3/schema/**` are verbatim upstream
+copies, checksummed in `docs/artifacts.sha256`. Do not edit them, not even whitespace.
+
+If `rake verify:artifacts` fails, upstream changed. That is a finding to investigate and
+ledger, not a checkout to repair. Refresh the files, update the manifest and the ledger,
+and describe the behavioural impact in your PR.
+
+## Constraints that are decided, not open
+
+Please raise these for discussion rather than changing them in a PR:
+
+- **Runtime dependencies are exactly four**: `faraday`, `nokogiri`, `bigdecimal`,
+  `zeitwerk`. A fifth needs a discussion first.
+- **No upper bound on `required_ruby_version`**, ever.
+- **The Ruby 3.2 floor stays**, despite 3.2 being EOL upstream — see DESIGN.md §3. Please
+  don't open a PR raising it, and don't reach for a 3.3+ API on the grounds that 3.2 is
+  past EOL.
+- **`BigDecimal` for every monetary amount.** `Float` is forbidden in any monetary path.
+- **Invoice submission is never auto-retried.**
+- **No `VERIFY_NONE`**, no way to disable TLS verification.
+- `lib/ksef/fa3/generated/` is codegen output — regenerate with `rake fa3:generate`, never
+  hand-edit.
+
+## Style
+
+- `# frozen_string_literal: true` in every file.
+- `Data.define` for immutable value and response objects.
+- UTF-8 throughout; XML serialised with an explicit `encoding="UTF-8"` declaration. Note
+  that file reads need an explicit encoding, since a non-UTF-8 locale otherwise yields
+  US-ASCII strings and breaks on Polish characters.
+- No `RUBY_VERSION` string surgery.
+- RuboCop enforces what it can; `bundle exec rubocop -a` for the mechanical parts.
+
+## Tests
+
+| Tier | Runs |
+|---|---|
+| Unit + recorded (WebMock/VCR) | every push, full Ruby matrix |
+| Golden files, round-trip, crypto vectors | every push |
+| Live TEST integration | nightly and pre-release only, never per-PR |
+
+Coverage gate is 90% lines, excluding `generated/`. Live integration specs are tagged
+`:integration` and read credentials only from `KSEF_TEST_NIP` / `KSEF_TEST_TOKEN` with
+`KSEF_ENV=test`.
+
+Never point tests at production. The suite aborts on `KSEF_ENV=prod`.
+
+Cassettes must be scrubbed of tokens, JWTs and keys before committing.
+
+## Releasing
+
+1. Confirm no metadata placeholders were reintroduced: `grep -r UNRESOLVED-DESIGN-12-1`.
+   The release gate checks this too, but it is cheaper to notice here.
+2. Update `CHANGELOG.md`, including the KSeF API version and FA schema revision targeted.
+3. Confirm a **green nightly on the release commit**.
+4. Do one deliberate local full-suite run on **Ruby 3.2** — the floor contract deserves a
+   look, not just a matrix tick. RuboCop cannot substitute for this: `TargetRubyVersion`
+   catches incompatible *syntax* but not post-3.2 *APIs*, so a method added in 3.3 or 3.4
+   passes lint and then `NoMethodError`s on a user's interpreter.
+
+   ```bash
+   mv Gemfile.lock /tmp/Gemfile.lock.dev
+   BUNDLE_PATH=/tmp/ksef-bundle-32 RBENV_VERSION=3.2.11 bundle install
+   BUNDLE_PATH=/tmp/ksef-bundle-32 RBENV_VERSION=3.2.11 bundle exec rake
+   mv /tmp/Gemfile.lock.dev Gemfile.lock
+   ```
+
+   The separate `BUNDLE_PATH` leaves your development gem set alone, and resolving without
+   the lockfile mirrors CI. Bundler on 3.2 cannot read a lockfile written by Bundler 4.
+5. Tag `vX.Y.Z`. The release workflow runs the suite with `KSEF_RELEASE_CHECK=1`, checks
+   the tag against `Ksef::VERSION`, and publishes via Trusted Publishing.

data/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Tibor Molnár
+
+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.
+
+---
+
+The FA(3) XML schemas bundled under `lib/ksef/fa3/schema/` are published by
+Ministerstwo Finansów under the MIT licence; see
+`lib/ksef/fa3/schema/LICENSE.upstream.txt` and docs/REFERENCE.md §1.

data/README.md

@@ -0,0 +1,150 @@
+# ksef_client
+
+Ruby client for **KSeF 2.0**, Poland's national e-invoicing system (Krajowy System
+e-Faktur), with a standalone **FA(3)** invoice builder.
+
+Invoicing through KSeF has been a legal obligation since 2026-02-01 for taxpayers with
+2024 gross sales above 200M PLN, and since 2026-04-01 for essentially everyone else. The
+Ministry of Finance publishes official SDKs in C# and Java; this gem fills the Ruby gap.
+
+> **Status: pre-release, under active development.** The transport foundations
+> (configuration, environments, error model, HTTP layer) are in place. Authentication,
+> encryption, sessions and the FA(3) builder are not implemented yet — see
+> [Roadmap](#roadmap). The quickstart below is the **target** API for 0.1.0 and does not
+> run today.
+
+## Installation
+
+```ruby
+gem "ksef_client"
+```
+
+The gem is named `ksef_client`; the namespace is `Ksef`.
+
+```ruby
+require "ksef_client"   # defines Ksef, Ksef::Client, Ksef::FA3, ...
+```
+
+## Quickstart (target API for 0.1.0 — not yet functional)
+
+```ruby
+client = Ksef::Client.new(
+  env:  :test,
+  auth: Ksef::Auth::Token.new(context_nip: "9999999999", token: ENV["KSEF_TOKEN"])
+)
+
+invoice = Ksef::FA3.build do |f|
+  f.seller nip: "9999999999", name: "ACME sp. z o.o.",
+           address: { street: "Prosta 1", city: "Warszawa", postal_code: "00-001", country: "PL" }
+  f.buyer  nip: "1111111111", name: "Klient S.A.",
+           address: { street: "Długa 2", city: "Kraków", postal_code: "30-001", country: "PL" }
+  f.number "FV/2026/08/001"
+  f.issue_date Date.today
+  f.line name: "Consulting", qty: 10, unit: "godz.", net_unit_price: 150, vat: "23"
+end
+
+result = client.send_invoice(invoice)          # validate! → encrypt → session → submit
+status = client.wait_until_accepted(result.reference)
+status.ksef_number                             # => "9999999999-2026…"
+upo    = client.upo(result.reference)          # signed UPO XML — archive this verbatim
+```
+
+## What works today
+
+```ruby
+config = Ksef::Configuration.new(env: :test, timeout: { read: 120 })
+config.base_url        # => "https://api-test.ksef.mf.gov.pl/v2"
+config.inspect         # credentials are redacted, never logged
+
+conn = Ksef::HTTP::Connection.build(config)
+conn.get("rate-limits")
+```
+
+Errors from the API arrive as a typed hierarchy carrying the Ministry's own diagnostics:
+
+```ruby
+begin
+  conn.get("sessions")
+rescue Ksef::RateLimitedError => e
+  e.retry_after      # => 30 — seconds, from the Retry-After header. Honour it.
+rescue Ksef::AuthorizationError => e
+  e.reason_code      # => "missing-permissions"
+  e.security         # => {"requiredAnyOfPermissions" => ["InvoiceWrite"], ...}
+rescue Ksef::ApiError => e
+  e.status           # => 400
+  e.code             # => 21405
+  e.details          # => ["Wskazany kod formularza nie jest wspierany."]
+  e.trace_id         # quote this to Ministry support
+end
+```
+
+## Environments
+
+| Env | Base URL |
+|---|---|
+| `:test` | `https://api-test.ksef.mf.gov.pl/v2` |
+| `:demo` | `https://api-demo.ksef.mf.gov.pl/v2` |
+| `:prod` | `https://api.ksef.mf.gov.pl/v2` |
+
+Each URL was verified against that environment's own OpenAPI document; see
+[`docs/REFERENCE.md`](docs/REFERENCE.md). Note the base URL already includes `/v2`.
+`Ksef::Environments.custom(base_url:)` is available for non-public deployments.
+
+TEST and DEMO are for integration testing only — never send real invoices or real
+taxpayer data to them, and use random NIPs. TEST data is not isolated between
+integrators.
+
+## Ruby support
+
+- **MRI >= 3.2**, with **no upper bound, ever.** `required_ruby_version` resolves at
+  install time, so an upper bound strands users on each new Ruby release.
+- CI covers 3.2, 3.3, 3.4, 4.0 and `head`, and the full suite is run on 3.2 at every
+  milestone — the floor is verified, not just declared.
+- **The 3.2 floor is a commitment, not a default.** Ruby 3.2 is EOL upstream, and this gem
+  still supports it deliberately: Polish tax-compliance software upgrades slowly, and 3.2
+  is the Rails 8.0 floor. There is no plan to raise it.
+- Later EOL series will be dropped in **minor** releases with a changelog note. Because
+  version constraints resolve at install time, users on an older Ruby keep receiving the
+  last compatible release.
+- **MRI only.** JRuby and TruffleRuby are untested — the crypto layer needs precise
+  OpenSSL RSA-OAEP parameterisation. PRs welcome.
+
+## Design notes
+
+- **Two decoupled subsystems.** The FA(3) builder has no HTTP dependency and is usable on
+  its own; the transport layer accepts anything responding to `#to_xml`, or a raw XML
+  string.
+- **`BigDecimal` everywhere for money.** `Float` is forbidden in any monetary path.
+- **Invoice submission is never auto-retried.** A duplicate invoice in KSeF is a real tax
+  problem. Idempotent GETs retry with backoff; a failed submission surfaces to you.
+- **Thread-safe.** A single client is shareable across threads (Sidekiq is the expected
+  habitat); configuration is frozen at construction.
+- **Secrets never logged.** Tokens, JWTs, symmetric keys and IVs are redacted from
+  `#inspect` output.
+
+## Roadmap
+
+| Version | Scope |
+|---|---|
+| 0.1.0 | KSeF-token auth, crypto, online sessions, send/status/UPO/download, full FA(3) builder for all seven invoice types |
+| 0.2 | Batch sessions, invoice query/search, package export, hardened error catalogue |
+| 0.3 | XAdES authentication, certificate lifecycle, permissions API, offline QR codes |
+| 1.0 | After sustained production use; API stability promise begins |
+
+## Development
+
+```bash
+bin/setup            # or: bundle install
+bundle exec rake     # verify pinned artifacts, specs, RuboCop
+```
+
+Every externally sourced fact — endpoint paths, XML element names, namespace URIs,
+crypto parameters — is recorded with its source and retrieval date in
+[`docs/REFERENCE.md`](docs/REFERENCE.md). Nothing enters the code without an entry there.
+
+## Licence
+
+MIT. The bundled FA(3) schemas are published by Ministerstwo Finansów, also under MIT;
+see `lib/ksef/fa3/schema/LICENSE.upstream.txt`.
+
+This project is not affiliated with or endorsed by the Polish Ministry of Finance.

data/SECURITY.md

@@ -0,0 +1,69 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please report security issues privately via GitHub's "Report a vulnerability" flow on
+this repository, rather than opening a public issue. You can expect an acknowledgement
+within a few working days.
+
+This gem handles credentials that authenticate against a tax authority, and invoice
+payloads that are legally binding documents. Reports about credential leakage, weakened
+TLS, or incorrect cryptographic parameters are treated as high severity.
+
+## Supported versions
+
+Security fixes land on the latest minor release.
+
+The supported interpreter range is whatever `required_ruby_version` declares — currently
+**MRI >= 3.2**. Note that this **includes Ruby 3.2 even though 3.2 is EOL upstream**: the
+floor is a deliberate commitment (see DESIGN.md §3), so 3.2 users do receive fixes from
+this gem.
+
+That said, an EOL interpreter stops receiving fixes for CVEs *in Ruby itself*, which this
+project cannot patch. If you are on 3.2 for compliance reasons, upgrading Ruby is still
+the stronger position.
+
+Once a series does fall below the floor in a future minor release, `required_ruby_version`
+resolves at install time, so users on that interpreter stay on the last compatible release
+and stop receiving fixes from us.
+
+## Handling of secrets
+
+The following must never appear in logs, `#inspect` output, exception messages, or test
+fixtures:
+
+- KSeF tokens and JWTs (access and refresh)
+- Session symmetric keys and IVs
+- Full invoice payloads at default log level
+
+Enforced by:
+
+- A redacting `#inspect` on configuration and authentication objects.
+- VCR cassette scrubbing, plus a spec that scans committed cassettes for `Bearer ` and
+  known secret environment values.
+- Integration tests reading credentials only from environment variables
+  (`KSEF_TEST_NIP`, `KSEF_TEST_TOKEN`, `KSEF_ENV=test`).
+
+## Transport security
+
+- TLS verification is always on. No code path may set `VERIFY_NONE`; there is no
+  configuration option to disable it.
+- Minimum TLS version is 1.2.
+
+## Testing against production
+
+The test suite aborts if `KSEF_ENV=prod`, and the nightly workflow fails the same way.
+Never point automated tests at the production environment — invoices submitted there have
+full legal force.
+
+## Rate limits
+
+KSeF records and analyses rate-limit breaches, and explicitly treats spreading one
+context across many IP addresses as an abuse pattern. This client honours `Retry-After`
+and will never work around a 429 by rotating connections. Please do not add such a
+mechanism.
+
+## Publishing
+
+Releases use RubyGems Trusted Publishing (OIDC). No long-lived RubyGems API key exists
+for this project. The gemspec sets `rubygems_mfa_required`.