tamga-sdk 0.1.0__tar.gz

tamga_sdk-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,15 @@
+# See https://docs.github.com/articles/about-codeowners for syntax.
+# Later matches take precedence.
+
+* @tamga-sh/sdk-maintainers
+
+# Crypto-bearing paths require a security-focused reviewer on every change —
+# mirrors the mandatory security-reviewer gate in docs/plans/tamga-python.plan.md
+# Section 4 for Sections E, F, H.
+/src/tamga/crypto/    @tamga-sh/sdk-maintainers @tamga-sh/security
+/src/tamga/checkout/  @tamga-sh/sdk-maintainers @tamga-sh/security
+/src/tamga/proof.py   @tamga-sh/sdk-maintainers @tamga-sh/security
+
+/.github/workflows/   @tamga-sh/sdk-maintainers
+/release-please-config.json          @tamga-sh/sdk-maintainers
+/.release-please-manifest.json       @tamga-sh/sdk-maintainers

tamga_sdk-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,84 @@
+name: Bug Report
+description: Report a problem with this SDK
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the sections below as completely as possible — a minimal reproduction is the single most useful thing you can include.
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal, self-contained code sample that reproduces the issue.
+      render: "python"
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened, including the full error/exception/stack trace if there is one.
+      render: shell
+    validations:
+      required: true
+  - type: input
+    id: sdk-version
+    attributes:
+      label: SDK Version
+      placeholder: "e.g. 1.0.3"
+    validations:
+      required: true
+  - type: input
+    id: runtime-version
+    attributes:
+      label: Python Version
+      placeholder: "e.g. 3.12.1"
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: "e.g. macOS 15, Ubuntu 24.04, Windows 11"
+    validations:
+      required: false
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Which part of the SDK does this affect, if known?
+      multiple: true
+      options:
+        - License validation / check-in / check-out
+        - Machine management (activation, heartbeats, components, processes)
+        - Offline license/machine file verification
+        - Offline proof generation/verification
+        - Entitlements
+        - Auth transports
+        - Other / not sure
+    validations:
+      required: false
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: I have searched existing issues to make sure this is not a duplicate.
+          required: true
+        - label: I have included a minimal reproduction and the version fields above.
+          required: true

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

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security Vulnerability
+    url: https://github.com/tamga-sh/tamga-python/security/policy
+    about: Please report security vulnerabilities privately — do not open a public issue.

tamga_sdk-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,48 @@
+name: Feature Request
+description: Suggest an addition to this SDK
+title: "[Feature]: "
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement! Please fill out the sections below.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Motivation
+      description: What are you trying to do, and why doesn't the current SDK support it?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: What you want to happen — a proposed method signature or API shape if you have one in mind.
+    validations:
+      required: true
+  - type: textarea
+    id: server-check
+    attributes:
+      label: Is this feature actually available server-side?
+      description: >-
+        Before requesting an SDK feature, please check tamga-api's docs/sdk.md
+        (https://github.com/tamga-sh/tamga-api/blob/main/docs/sdk.md), especially the
+        "Known Server-Side Gaps" section — several documented server features are not
+        actually wired up server-side yet. A feature request for one of those will be
+        tracked as blocked on server-side work rather than implemented here.
+    validations:
+      required: false
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+    validations:
+      required: false
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: I have searched existing issues to make sure this is not a duplicate.
+          required: true

tamga_sdk-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+## Summary
+
+<!-- What does this PR do, and why? -->
+
+## Related plan section(s)
+
+<!-- e.g. Section E (License Checkout Crypto) — see docs/plans/tamga-python.plan.md -->
+
+## Checklist
+
+- [ ] `uv run ruff check .` passes
+- [ ] `uv run ruff format --check .` passes
+- [ ] `uv run mypy src/` passes
+- [ ] `uv run pytest --cov=tamga --cov-fail-under=80` passes
+- [ ] Tests were written alongside the implementation (TDD), not bolted on after
+- [ ] If this touches `src/tamga/crypto/`, `src/tamga/checkout/`, or `src/tamga/proof.py`: a
+      `security-reviewer` pass was requested and CRITICAL/HIGH findings addressed (see
+      `CONTRIBUTING.md` and `docs/plans/tamga-python.plan.md` Section 4)
+- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
+- [ ] Plan checkboxes updated in `docs/plans/tamga-python.plan.md`, with an inline note for any
+      deviation from the plan's literal wording
+
+## Test plan
+
+<!-- How did you verify this works? -->

tamga_sdk-0.1.0/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      dev-dependencies:
+        patterns:
+          - "ruff"
+          - "mypy"
+          - "pytest*"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "ci"

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

@@ -0,0 +1,78 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: ruff check
+        run: uv run ruff check .
+
+      - name: ruff format --check
+        run: uv run ruff format --check .
+
+      - name: mypy
+        run: uv run mypy src/
+
+      - name: pytest (with coverage gate)
+        run: uv run pytest --cov=tamga --cov-fail-under=80 --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+          # Required when CODECOV_TOKEN is the org's shared Global Upload
+          # Token (one token for every Tamga SDK repo) rather than a
+          # per-repo token — without it Codecov can't tell which repo an
+          # upload belongs to.
+          slug: tamga-sh/tamga-python
+
+  smoke:
+    name: smoke (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: pytest
+        run: uv run pytest

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

@@ -0,0 +1,61 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  # Runs on every push to main: opens/updates a release PR that accumulates
+  # the changelog, or (when a release PR is merged) tags + creates the
+  # GitHub Release directly.
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          release-type: python
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  # Runs only right after release-please's own step above actually created a
+  # release (i.e. this run was the release-PR-merge push) — builds and
+  # publishes to PyPI via Trusted Publishing (OIDC), no long-lived API token
+  # stored as a repo secret.
+  #
+  # Deliberately gated via this job's `needs`/`if` on the release-please
+  # job's output, in the SAME workflow run, rather than a separate
+  # `on: release: types: [published]` trigger: release-please-action
+  # creates that GitHub Release using this workflow's own GITHUB_TOKEN, and
+  # GitHub does not let GITHUB_TOKEN-authored events trigger further
+  # workflow runs (loop-prevention) — so a `release: published` trigger
+  # here would simply never fire.
+  publish:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write # required for PyPI Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

tamga_sdk-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.env
+*.log
+.DS_Store

tamga_sdk-0.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

tamga_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. This file is maintained by
+[release-please](https://github.com/googleapis/release-please) from
+[Conventional Commits](https://www.conventionalcommits.org/) history — do not hand-edit entries
+below the `[Unreleased]` header.
+
+## 0.1.0 (2026-08-11)
+
+
+### Features
+
+* implement license/machine validation, checkout crypto, and error model (Sections B-K) ([d0524d8](https://github.com/tamga-sh/tamga-python/commit/d0524d822e4b323b071906e2b19a71fe1a90d069))
+
+
+### Bug Fixes
+
+* **ci:** gate PyPI publish on release-please's own job output ([b352422](https://github.com/tamga-sh/tamga-python/commit/b35242271ffb6dfb845cadd07dda9aacfc6791ae))
+
+
+### Documentation
+
+* add README, examples, CHANGELOG, CONTRIBUTING, SECURITY, GitHub templates (Sections L-M) ([6307ceb](https://github.com/tamga-sh/tamga-python/commit/6307cebc047d7ab3d90fa41b2185baac0632b6ff))
+* remove dead docs/plans references, add status badges where CI is live ([7971490](https://github.com/tamga-sh/tamga-python/commit/79714904468fc6abcf5893c53a4b491e32eca768))
+
+## [Unreleased]

tamga_sdk-0.1.0/CLAUDE.md

@@ -0,0 +1,198 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`tamga-python` is the official Python SDK for Tamga, a license-management API. It is one of the
+five independently hand-written SDKs in the Tamga family (alongside `tamga-rust`, `tamga-go`,
+`tamga-dotnet`, `tamga-js`) — unlike `tamga-c`/`tamga-java`/`tamga-swift`, this package
+re-implements the full validation and cryptographic-verification surface natively in Python rather
+than binding to the Rust reference implementation via FFI.
+
+Full task-by-task build plan: [`docs/plans/tamga-python.plan.md`](docs/plans/tamga-python.plan.md).
+Authoritative wire-level protocol reference (endpoints, field names, enum values, and the
+**Known Server-Side Gaps** section — read that before touching anything protocol-shaped):
+[`tamga-api`'s `docs/sdk.md`](https://github.com/tamga-sh/tamga-api/blob/main/docs/sdk.md).
+
+**Repo status:** scaffold only. Every module under `src/tamga/` is a typed stub — real
+docstrings and signatures, `raise NotImplementedError`/`...` bodies. Do not assume any endpoint or
+crypto path actually works; check the plan file's checkbox state before relying on something.
+
+## Architecture
+
+Pure Python, no Rust extension, no native build step. `hatchling` build backend, src-layout.
+`cryptography` (pyca) supplies every crypto primitive (Ed25519, RSA-PKCS1/PSS, ECDSA-P256,
+AES-256-GCM, HKDF); `httpx` supplies the HTTP transport.
+
+```
+src/tamga/
+├── __init__.py         # public re-exports: TamgaClient, TamgaConfig, errors, __version__
+├── py.typed             # PEP 561 marker
+├── client.py             # TamgaClient façade + namespaced sub-clients (licenses/machines/
+│                         #   components/processes/entitlements) + all endpoint methods
+├── transport.py          # httpx wiring, 5 auth transports, header handling
+├── proof.py               # offline proof payload build + verify
+├── errors.py               # TamgaError hierarchy, JSON:API error envelope parsing
+├── models/
+│   ├── validation.py     # ValidationCode (24 members), ValidationMeta, ValidationResult
+│   ├── license.py        # LicenseResource, LicenseScope, LicenseFileResource
+│   ├── machine.py        # MachineResource, ComponentResource, ProcessResource, HeartbeatStatus
+│   └── policy.py         # PolicyResource + policy-derived enums, Entitlement
+├── crypto/
+│   ├── ed25519.py         # Ed25519 verify (license checkout, one of 4 machine-checkout schemes)
+│   ├── rsa.py              # RSA-PKCS1v15 + RSA-PSS verify (machine checkout, offline proof)
+│   ├── ecdsa.py            # ECDSA-P256 verify (machine checkout)
+│   ├── aes_gcm.py          # AES-256-GCM decrypt (both checkout flows)
+│   ├── hkdf.py              # HKDF-SHA256 machine-file key derivation
+│   └── naive_key.py        # non-KDF zero-pad/truncate license-file key derivation
+└── checkout/
+    ├── license_file.py    # .lic parse + verify pipeline
+    └── machine_file.py    # machine-file parse + multi-scheme verify pipeline
+```
+
+**Vertical-ish grouping, not one flat client.** `TamgaClient` exposes `.licenses`, `.machines`,
+`.components`, `.processes`, `.entitlements` sub-clients instead of one giant method namespace —
+mirrors the resource grouping in `docs/sdk.md`, keep new endpoint methods on the matching
+sub-client rather than bolting everything onto `TamgaClient` directly.
+
+**Crypto stays out of `client.py`.** Signature verification and key derivation live under
+`crypto/`, one primitive per file, so a security review can be scoped to exactly the files that
+changed. `checkout/license_file.py` and `checkout/machine_file.py` orchestrate `crypto/` calls but
+never implement a primitive inline.
+
+## Dev Commands
+
+This repo uses [`uv`](https://docs.astral.sh/uv/) for environment and dependency management.
+
+```bash
+uv sync --all-extras --dev   # install runtime + dev deps into .venv
+uv run pytest                 # run tests
+uv run pytest --cov=tamga --cov-fail-under=80 --cov-report=term-missing   # tests + coverage gate
+uv run ruff check .            # lint
+uv run ruff check --fix .       # lint, auto-fix
+uv run ruff format .             # format
+uv run ruff format --check .      # format check (CI mode, no writes)
+uv run mypy src/                   # type check (strict mode — see pyproject.toml [tool.mypy])
+uv build                            # build sdist + wheel
+uv publish                           # manual/local publish — see "Release" below
+```
+
+There is no single `just check`-style umbrella command yet (unlike `tamga-api`) — CI runs each
+step above individually; see `.github/workflows/ci.yml` for the exact order
+(ruff check → ruff format --check → mypy → pytest+coverage).
+
+## GOTCHAS
+
+### This SDK's own crypto traps
+
+- **Signing-message trap (license checkout).** The Ed25519 signature in a `.lic` file covers
+  `enc`'s **base64 string bytes** (`enc.encode("ascii")`), not `base64.b64decode(enc)`. Getting
+  this backwards makes every signature fail to verify even with the correct key and data. See
+  `checkout/license_file.py`'s module docstring and the dedicated regression test called for in
+  the plan (Section E).
+- **Naive key derivation is not a KDF (license checkout).** `crypto/naive_key.py` must NOT become
+  a real hash/KDF. It is `license.key`'s raw UTF-8 bytes, zero-padded/truncated to exactly 32
+  bytes — matching the server's exact (deliberately naive) transform. "Fixing" this into PBKDF2 or
+  SHA-256 breaks decryption against every license file the server has ever issued.
+- **Byte-exact serialization (offline proof).** The RSA signature over an offline-proof payload
+  covers `{"account":{...},"machine":{...},"dataset":...}` serialized in exactly that key order.
+  Field *presence* matching isn't enough — reordering the same fields into valid-but-different JSON
+  must produce a different signed message. Build via an explicitly ordered structure +
+  `json.dumps(..., separators=(",", ":"))`, never rely on incidental dict-ordering.
+- **`RSA_2048_JWT_RS256` is rejected, not unsupported-and-ignored.** Machine-checkout scheme
+  dispatch must raise `SchemeNotSupportedError` for this scheme explicitly — don't let it fall
+  through to a different verifier, and don't silently skip verification.
+- **`pid` is a string on the wire.** `ProcessResource.pid` and `processes.create(..., pid=...)` are
+  typed `str`, matching the server exactly. Reject `int` input at the call boundary; don't
+  `str()`-coerce it — that hides a caller bug instead of surfacing it.
+- **`"DENY_ACCESS"` / `"NO_RESURRECTION"` are not real enum variants.** Freshly-created policies
+  report these as their `overage_strategy`/`heartbeat_resurrection_strategy` defaults, but neither
+  string is a valid member of `OverageStrategy`/`HeartbeatResurrectionStrategy`. Both silently
+  behave as `NO_OVERAGE`/`NO_REVIVE` server-side — `PolicyResource` parsing must apply that
+  fallback, not trust the field name's implication that access is denied by default.
+
+### `docs/sdk.md` "Known Server-Side Gaps" that apply to this repo
+
+Only the gaps relevant to this SDK's actual scope (license validation, checkout, machine
+management, entitlements) are listed — see the upstream doc for the full list, including
+analytics/EE items that don't touch this package at all.
+
+- **Auth is not enforced server-side on license/machine endpoints** (gap #3). Send
+  `Authorization: License <key>` (or another transport) on every call anyway — it's
+  forward-compatible for when enforcement lands, but don't build any test or example that asserts
+  a *missing* credential gets rejected today; it won't be.
+- **Only 14 of 24 `ValidationCode` values are reachable** (gap #4). Model all 24 in
+  `ValidationCode` with a lenient unknown-value fallback, but don't write tests or docs implying
+  the other 10 (`BANNED`, `ENTITLEMENTS_MISSING`, `TOO_MANY_USERS`, `HEARTBEAT_DEAD`,
+  `HEARTBEAT_NOT_STARTED`, `FINGERPRINT_SCOPE_MISMATCH`, `COMPONENTS_SCOPE_MISMATCH`,
+  `CHECKSUM_SCOPE_MISMATCH`, `VERSION_SCOPE_MISMATCH`, plus `NOT_FOUND` which comes back as a raw
+  HTTP 404 instead) can currently occur.
+- **No in-app rate limiting; `429` is never returned** (gap #5). Do not implement client-side
+  429/backoff handling, `X-RateLimit-*` header parsing, or retry-with-backoff logic — there is
+  nothing on the other end to trigger it, and code written to expect it will just be dead code.
+- **`Tamga-Environment` header is not implemented** (gap #7). Don't add it to `transport.py`'s
+  request headers even though it's documented as a planned EE feature — no server code path reads
+  it yet.
+- **`heartbeat_status` ignores `policy.heartbeat_duration`** (gap #8). The window is a hardcoded
+  600s for machines regardless of what a license's policy declares. `HeartbeatScheduler`'s
+  recommended interval (~200s) is sized against that hardcoded constant, not against
+  `policy.heartbeat_duration` — don't wire the scheduler to read the policy value, it wouldn't
+  matter server-side anyway.
+- **RFC 9421 response signing is dead code** (gap #6) and the auto-update/release-check endpoint
+  is unusable (`docs/sdk.md` §12). Neither is in this SDK's scope at all — there is no
+  `releases` sub-client and none should be added until the server side is real.
+
+## Testing
+
+- Coverage gate: `--cov-fail-under=80`, enforced in CI via `pytest --cov=tamga --cov-fail-under=80`.
+  Run the same command locally before opening a PR.
+- Fixtures live in `tests/conftest.py` (mock-transport HTTP client, throwaway Ed25519/RSA/ECDSA
+  keypairs) and `tests/fixtures/` (sample `.lic`/machine-file certificates, canned JSON:API error
+  bodies) — reuse these rather than hand-rolling new keypairs or HTTP mocks per test file.
+  `httpx.MockTransport` is a hard requirement for HTTP tests; do not spin up a real server or mock
+  at the `requests` level.
+- Sections E, F, H (all three crypto-bearing sections) require a **mandatory, non-skippable**
+  `security-reviewer` pass before merge — see `docs/plans/tamga-python.plan.md` Section 4. A
+  `python-reviewer`-only pass is not sufficient for those sections.
+- Golden-byte/known-answer tests matter more than structural-equality tests for the crypto paths —
+  e.g. the offline-proof payload test must assert an exact expected byte string, and the HKDF
+  derivation test must assert an exact 32-byte key for a fixed input, not just "produces 32 bytes".
+
+## Critical Dependency Notes
+
+- **`cryptography` (pyca) is the sole crypto dependency.** It wraps OpenSSL/BoringSSL under the
+  hood and covers all four algorithm families this SDK needs (Ed25519, RSA, ECDSA, AES-GCM) plus
+  HKDF. Do not add `pynacl`, `pycryptodome`, or any other crypto library as an alternate/backup for
+  something `cryptography` already covers — that doubles the audit surface for no benefit.
+- **`httpx`, not `requests`.** Async-capable, has first-class `MockTransport` support for tests,
+  and is what `transport.py` and `tests/conftest.py` are built around. Don't introduce `requests`
+  or `urllib3` calls anywhere in `src/tamga/`.
+- **`mypy --strict`.** Every public function needs real type hints, not `Any` escape hatches,
+  except where a value is genuinely opaque server-side (e.g. token strings — see the `tok-` prefix
+  gotcha below).
+- **mypy is pinned to `<2`.** mypy 2.0 dropped support for checking against `python_version =
+  "3.9"` (our `[tool.mypy]` target, matching `requires-python`) — running `uv run mypy src/` with
+  an unpinned/2.x mypy either errors outright or silently checks against the wrong Python version.
+  Don't remove the `<2` pin without also bumping `requires-python` and the CI matrix's floor.
+- **Every issued server token is `tok-`-prefixed regardless of documented type.** Do not build
+  prefix-based token type detection into `transport.py`; treat all bearer tokens as opaque strings.
+
+## Release
+
+`release-please` (config: `release-please-config.json`, manifest:
+`.release-please-manifest.json`) tracks `pyproject.toml`'s `version` and
+`src/tamga/__init__.py`'s `__version__` together, opening/updating a release PR with the generated
+changelog on every push to `main`. Publishing to PyPI happens on `release: published` via
+`pypa/gh-action-pypi-publish@release/v1` using **PyPI Trusted Publishing (OIDC)** —
+there is no `PYPI_API_TOKEN` secret in this repo, and one should not be added.
+
+**Manual/local publish** (only if ever needed outside CI): `uv publish`, not `twine` — keep the
+tooling consistent between CI and any manual escape hatch.
+
+## Branch & Commit Convention
+
+Branches: `feat/*`, `fix/*`, `chore/*`, `refactor/*`, `docs/*`
+Commits: [Conventional Commits](https://www.conventionalcommits.org/) format (`feat: …`, `fix: …`,
+etc.) — `release-please` parses these to compute the next version and changelog entry, so
+non-conforming commit messages silently produce no release.

tamga_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to tamga-python
+
+## Dev setup
+
+This repo uses [`uv`](https://docs.astral.sh/uv/) for environment and dependency management.
+
+```bash
+uv sync --all-extras --dev   # install runtime + dev deps into .venv
+```
+
+## Commands
+
+There is no single `just check`-style umbrella command yet — run each step individually, in the
+order CI runs them (`.github/workflows/ci.yml`):
+
+```bash
+uv run ruff check .                                                        # lint
+uv run ruff format --check .                                                # format check
+uv run mypy src/                                                              # type check (strict)
+uv run pytest --cov=tamga --cov-fail-under=80 --cov-report=term-missing        # tests + coverage
+```
+
+Auto-fix locally before committing:
+
+```bash
+uv run ruff check --fix .
+uv run ruff format .
+```
+
+## Test-driven development
+
+Write the test in the same task as the implementation, not after — see
+[`docs/plans/tamga-python.plan.md`](docs/plans/tamga-python.plan.md) for the section-by-section
+task breakdown. Fixtures live in `tests/conftest.py` (mock-transport HTTP client via
+`httpx.MockTransport`, throwaway Ed25519/RSA/ECDSA keypairs) — reuse these rather than
+hand-rolling new ones per test file.
+
+Golden-byte/known-answer tests matter more than structural-equality tests for the crypto paths —
+e.g. the offline-proof payload test asserts an exact expected byte string, and the HKDF
+derivation test asserts an exact 32-byte key for a fixed input, not just "produces 32 bytes".
+
+## Crypto changes require a security review
+
+Any change touching `src/tamga/crypto/`, `src/tamga/checkout/`, or `src/tamga/proof.py` requires
+a `security-reviewer` pass before merge — a general code-quality review alone is not sufficient.
+See [`docs/plans/tamga-python.plan.md`](docs/plans/tamga-python.plan.md) Section 4 (Quality
+Gates) and [`SECURITY.md`](SECURITY.md) for the specific assumptions those files encode.
+
+## Pull request expectations
+
+- Conventional Commits format (`feat: …`, `fix: …`, `docs: …`, etc.) — `release-please` parses
+  commit history directly to compute the next version and generate `CHANGELOG.md`; a
+  non-conforming commit type can silently skip a release.
+- Required checks before requesting review (these are also what CI enforces — see
+  `.github/workflows/ci.yml`): `ruff check`, `ruff format --check`, `mypy src/`, and
+  `pytest --cov=tamga --cov-fail-under=80` all passing. Branch protection on `main` should require
+  all of these plus the full Python version matrix (3.9–3.13) before merge.
+- Keep PRs scoped to one plan section (or one bug/feature) where practical — crypto-bearing
+  sections in particular should not be batched with unrelated changes, so a security review can
+  stay scoped to exactly the files that changed.
+
+## Branch & commit convention
+
+Branches: `feat/*`, `fix/*`, `chore/*`, `refactor/*`, `docs/*`.
+
+## Release
+
+Handled by CI (`release-please` + PyPI Trusted Publishing) — see [`CLAUDE.md`](CLAUDE.md)'s
+"Release" section. Manual/local publish, if ever needed: `uv build && uv publish` (not `twine`).