trustplane-auth-sdk 0.1.0rc1__tar.gz

trustplane_auth_sdk-0.1.0rc1/.github/workflows/pr.yml

@@ -0,0 +1,43 @@
+name: pr
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - "feature/**"
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Upgrade pip
+        run: python -m pip install -U pip
+      - name: Install package and dev dependencies
+        run: python -m pip install -e ".[dev]"
+      - name: Format check
+        run: ruff format --check .
+      - name: Lint
+        run: ruff check .
+      - name: Type check
+        run: mypy
+      - name: Tests
+        run: pytest
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Clean wheel install/import smoke
+        run: scripts/smoke-wheel.sh
+      - name: Leak scan
+        run: scripts/scan-leaks.sh
+      - name: Wording scan
+        run: scripts/scan-wording.sh

trustplane_auth_sdk-0.1.0rc1/.github/workflows/release-pypi.yml

@@ -0,0 +1,226 @@
+name: Manual PyPI Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: TrustPlane release tag to prepare, for example v0.1.0-rc.1
+        required: true
+        type: string
+      publish_package:
+        description: Publish to PyPI, create the release commit, and push the annotated tag
+        required: true
+        default: false
+        type: boolean
+
+permissions:
+  contents: write
+  id-token: write
+
+env:
+  PACKAGE_NAME: trustplane-auth-sdk
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require main
+        run: |
+          if [ "${GITHUB_REF_NAME}" != "main" ]; then
+            echo "release workflow must run from main"
+            exit 1
+          fi
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Upgrade pip
+        run: python -m pip install -U pip
+      - name: Install package and dev dependencies
+        run: python -m pip install -e ".[dev]"
+      - name: Configure release git identity
+        run: |
+          git config user.name "Medh Mesh"
+          git config user.email "maintainer@trustplane.dev"
+      - name: Validate version input
+        run: |
+          if ! printf '%s\n' "${{ inputs.version }}" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[0-9]+)?$'; then
+            echo "version must look like v0.1.0 or v0.1.0-rc.1"
+            exit 1
+          fi
+          python - <<'PY'
+          import os
+          import re
+
+          version = os.environ["INPUT_VERSION"]
+          match = re.fullmatch(r"v([0-9]+)\.([0-9]+)\.([0-9]+)(?:-rc\.([0-9]+))?", version)
+          if match is None:
+              raise SystemExit("invalid version")
+          major, minor, patch, rc = match.groups()
+          package_version = f"{major}.{minor}.{patch}"
+          if rc is not None:
+              package_version = f"{package_version}rc{rc}"
+          with open(os.environ["GITHUB_ENV"], "a", encoding="utf-8") as env:
+              env.write(f"PYTHON_PACKAGE_VERSION={package_version}\n")
+          print(f"TrustPlane version: {version}")
+          print(f"Python package version: {package_version}")
+          PY
+        env:
+          INPUT_VERSION: ${{ inputs.version }}
+      - name: Refuse existing git tag
+        run: |
+          if git rev-parse -q --verify "refs/tags/${{ inputs.version }}" >/dev/null; then
+            echo "local tag already exists: ${{ inputs.version }}"
+            exit 1
+          fi
+          if git ls-remote --exit-code --tags origin "refs/tags/${{ inputs.version }}" >/dev/null 2>&1; then
+            echo "remote tag already exists: ${{ inputs.version }}"
+            exit 1
+          fi
+      - name: Refuse existing PyPI version
+        run: |
+          python - <<'PY'
+          import json
+          import os
+          import sys
+          import urllib.error
+          import urllib.request
+
+          package_name = os.environ["PACKAGE_NAME"]
+          package_version = os.environ["PYTHON_PACKAGE_VERSION"]
+          url = f"https://pypi.org/pypi/{package_name}/json"
+          try:
+              with urllib.request.urlopen(url, timeout=20) as response:
+                  data = json.load(response)
+          except urllib.error.HTTPError as exc:
+              if exc.code == 404:
+                  print(f"PyPI project does not exist yet: {package_name}")
+                  sys.exit(0)
+              raise
+
+          if package_version in data.get("releases", {}):
+              raise SystemExit(f"PyPI version already exists: {package_name}=={package_version}")
+          print(f"PyPI version is unused: {package_name}=={package_version}")
+          PY
+      - name: Format check
+        run: ruff format --check .
+      - name: Lint
+        run: ruff check .
+      - name: Type check
+        run: mypy
+      - name: Tests
+        run: pytest
+      - name: Leak scan
+        run: scripts/scan-leaks.sh
+      - name: Wording scan
+        run: scripts/scan-wording.sh
+      - name: Verify clean worktree before version update
+        run: |
+          status="$(git status --short)"
+          printf '%s\n' "$status"
+          if [ -n "$status" ]; then
+            echo "worktree must be clean before version update"
+            exit 1
+          fi
+      - name: Set package version and README install command
+        run: |
+          python - <<'PY'
+          import os
+          from pathlib import Path
+
+          package_version = os.environ["PYTHON_PACKAGE_VERSION"]
+          path = Path("pyproject.toml")
+          lines = path.read_text(encoding="utf-8").splitlines()
+          changed = False
+          for index, line in enumerate(lines):
+              if line.startswith("version = "):
+                  lines[index] = f'version = "{package_version}"'
+                  changed = True
+                  break
+          if not changed:
+              raise SystemExit("pyproject.toml project version not found")
+          path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+          readme = Path("README.md")
+          text = readme.read_text(encoding="utf-8")
+          prefix, install_marker, rest = text.partition("## Install\n")
+          old_install, package_marker, suffix = rest.partition("## Package Name\n")
+          if install_marker == "" or package_marker == "":
+              raise SystemExit("README package section marker not found")
+          install_section = (
+              "## Install\n\n"
+              "Install released preview versions from PyPI with an exact version pin:\n\n"
+              "```sh\n"
+              f"python -m pip install trustplane-auth-sdk=={package_version}\n"
+              "```\n\n"
+              "For unreleased local changes, test this repository through a local checkout or built wheel.\n\n"
+          )
+          readme.write_text(prefix + install_section + package_marker + suffix, encoding="utf-8")
+          PY
+      - name: Verify only release metadata is dirty
+        run: |
+          status="$(git status --short)"
+          printf '%s\n' "$status"
+          python - <<'PY'
+          import subprocess
+
+          dirty = subprocess.check_output(
+              ["git", "diff", "--name-only"],
+              text=True,
+          ).splitlines()
+          if dirty != ["README.md", "pyproject.toml"]:
+              raise SystemExit(f"unexpected worktree state after version update: {dirty}")
+          PY
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Clean wheel install/import smoke
+        run: scripts/smoke-wheel.sh
+      - name: Dry-run summary
+        if: ${{ inputs.publish_package == false }}
+        run: |
+          {
+            echo "### PyPI release readiness complete"
+            echo
+            echo "Prepared and smoke-tested $PACKAGE_NAME==$PYTHON_PACKAGE_VERSION."
+            echo
+            echo "TrustPlane release version: ${{ inputs.version }}"
+            echo
+            echo "publish_package=false, so this run did not create a commit, tag, PyPI publish, or GitHub Release."
+            echo
+            echo "To publish later, rerun from main with publish_package=true after PyPI Trusted Publishing is configured."
+          } >> "$GITHUB_STEP_SUMMARY"
+      - name: Require PyPI Trusted Publishing
+        if: ${{ inputs.publish_package }}
+        run: |
+          if [ -z "${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-}" ] || [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ]; then
+            echo "PyPI Trusted Publishing/OIDC is not available to this job."
+            echo "Configure PyPI Trusted Publishing for $PACKAGE_NAME and keep id-token: write enabled."
+            exit 1
+          fi
+      - name: Publish package with PyPI Trusted Publishing
+        if: ${{ inputs.publish_package }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Commit version, tag, and push
+        if: ${{ inputs.publish_package }}
+        run: |
+          git add README.md pyproject.toml
+          git commit -m "Release Python SDK ${{ inputs.version }}"
+          git tag -a "${{ inputs.version }}" -m "TrustPlane Auth Python SDK ${{ inputs.version }}"
+          git push origin "HEAD:main" "refs/tags/${{ inputs.version }}"
+      - name: Publish summary
+        if: ${{ inputs.publish_package }}
+        run: |
+          {
+            echo "### PyPI release published"
+            echo
+            echo "Published $PACKAGE_NAME==$PYTHON_PACKAGE_VERSION with PyPI Trusted Publishing."
+            echo
+            echo "TrustPlane release version: ${{ inputs.version }}"
+            echo
+            echo "No GitHub Release was created by this workflow. Track any GitHub Release as a follow-up release task if repo policy later requires one."
+            echo
+            echo "Recovery note: PyPI publish runs before git commit/tag push. If PyPI publish fails, there is no release commit or tag to repair. If git push fails after PyPI publish, do not republish or overwrite PyPI; repair the git commit/tag publication from the same workflow commit and package version."
+          } >> "$GITHUB_STEP_SUMMARY"

trustplane_auth_sdk-0.1.0rc1/.gitignore

@@ -0,0 +1,9 @@
+/.mypy_cache/
+/.pytest_cache/
+/.ruff_cache/
+/build/
+/dist/
+/*.egg-info/
+/.venv/
+__pycache__/
+*.py[cod]

trustplane_auth_sdk-0.1.0rc1/AGENTS.md

@@ -0,0 +1,8 @@
+# Agent Instructions
+
+- Do not commit directly to `main`.
+- Use branch `feature/python-sdk-foundation` for TP-054A work.
+- Do not use a `[codex]` prefix in branch names, commits, PR titles, or PR bodies.
+- Every commit must be authored and committed as `Medh Mesh <maintainer@trustplane.dev>`.
+- Do not publish to PyPI, create tags, or create GitHub Releases from this repository.
+- Keep public docs free of private paths, personal names, token values, internal process chatter, and premature package availability claims.

trustplane_auth_sdk-0.1.0rc1/LICENSE

@@ -0,0 +1,51 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on or derived from the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link or bind by name to the interfaces of the Work.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner.
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+8. Limitation of Liability. In no event and under no legal theory shall any Contributor be liable to You for damages arising from use of the Work.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer support, warranty, indemnity, or other liability obligations. In accepting such obligations, You may act only on Your own behalf and on Your sole responsibility.

trustplane_auth_sdk-0.1.0rc1/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: trustplane-auth-sdk
+Version: 0.1.0rc1
+Summary: Python SDK foundation for TrustPlane Auth request material and local Ed25519 signing
+Project-URL: Homepage, https://github.com/trustplane-dev/trustplane-auth-sdk-python
+Project-URL: Repository, https://github.com/trustplane-dev/trustplane-auth-sdk-python
+Author: TrustPlane
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TrustPlane Auth SDK for Python
+
+Preview Python caller SDK for TrustPlane Auth request signing.
+
+This package provides caller-side helpers for:
+
+- building `transcript-v1` request material
+- computing body SHA-256 values
+- parsing passport claims needed by signing
+- raw local Ed25519 software signing
+- returning adapter-ready TrustPlane Auth headers
+
+It does not include a verifier, broker, adapter, policy engine, SPIFFE issuer, deployment code, enrollment flow, bundle mutation, or TrustPlane Control API.
+
+## Install
+
+Install released preview versions from PyPI with an exact version pin:
+
+```sh
+python -m pip install trustplane-auth-sdk==0.1.0rc1
+```
+
+For unreleased local changes, test this repository through a local checkout or built wheel.
+
+## Package Name
+
+The Python distribution name candidate is `trustplane-auth-sdk`.
+
+The import module is `trustplane_auth`:
+
+```python
+from trustplane_auth import body_sha256, build_request, sign_request
+```
+
+The package version remains `0.0.0` until the release workflow is introduced.
+
+PyPI trusted publishing is planned in a follow-up.
+
+## Build Request Example
+
+```python
+from trustplane_auth import SOFTWARE_KEY_BINDING, Header, build_request
+
+material = build_request(
+    method="POST",
+    scheme="https",
+    authority="orders.example",
+    path="/v1/orders",
+    audience="orders-api",
+    route_id="orders.create",
+    content_encoding="identity",
+    body=b'{"order_id":"ord_123","amount":"42.00"}',
+    headers=[
+        Header(name="Content-Type", value="application/json"),
+        Header(name="X-TrustPlane-Nonce", value="nonce-v1-001"),
+    ],
+    header_allow_list=["content-type", "x-trustplane-nonce"],
+    passport_jti="passport-v1-minimal-001",
+    nonce="nonce-v1-001",
+    issued_at_unix=1740000000,
+    key_binding=SOFTWARE_KEY_BINDING,
+)
+
+print(material.transcript_sha256)
+```
+
+## Signing Example
+
+Signing requires a real passport whose `cnf.key_binding` is `software` and whose `cnf.public_key_b64url` matches the Ed25519 private key.
+
+```python
+from pathlib import Path
+
+from trustplane_auth import Header, sign_request
+
+passport = "header.payload.signature"
+private_key_pem = Path("ed25519-private-key.pem").read_bytes()
+
+signed = sign_request(
+    request={
+        "method": "POST",
+        "scheme": "https",
+        "authority": "orders.example",
+        "path": "/v1/orders",
+        "route_id": "orders.create",
+        "content_encoding": "identity",
+        "body": b'{"order_id":"ord_123","amount":"42.00"}',
+        "headers": [
+            Header(name="Content-Type", value="application/json"),
+            Header(name="X-TrustPlane-Nonce", value="nonce-v1-001"),
+        ],
+        "header_allow_list": ["content-type", "x-trustplane-nonce"],
+        "nonce": "nonce-v1-001",
+    },
+    passport_token=passport,
+    private_key=private_key_pem,
+)
+
+headers = signed.headers
+```
+
+`sign_request` reads passport-bound fields from the passport and fails if caller-supplied consistency checks conflict. It does not infer or repair `aud`, `jti`, `iat`, `cnf.kid`, `cnf.key_binding`, or `cnf.public_key_b64url` from caller request inputs.
+
+## Conformance Posture
+
+`testdata/conformance/v1` contains public-safe contract vectors copied from the TrustPlane Auth reference. Tests assert exact canonical transcript lines, transcript SHA-256 values, and body SHA-256 values.
+
+## Security Rule
+
+This SDK signs only the verifier-rebuilt request transcript. Raw local signing is software-only and requires an Ed25519 private key whose public key exactly matches the passport `cnf.public_key_b64url` claim.

trustplane_auth_sdk-0.1.0rc1/README.md

@@ -0,0 +1,110 @@
+# TrustPlane Auth SDK for Python
+
+Preview Python caller SDK for TrustPlane Auth request signing.
+
+This package provides caller-side helpers for:
+
+- building `transcript-v1` request material
+- computing body SHA-256 values
+- parsing passport claims needed by signing
+- raw local Ed25519 software signing
+- returning adapter-ready TrustPlane Auth headers
+
+It does not include a verifier, broker, adapter, policy engine, SPIFFE issuer, deployment code, enrollment flow, bundle mutation, or TrustPlane Control API.
+
+## Install
+
+Install released preview versions from PyPI with an exact version pin:
+
+```sh
+python -m pip install trustplane-auth-sdk==0.1.0rc1
+```
+
+For unreleased local changes, test this repository through a local checkout or built wheel.
+
+## Package Name
+
+The Python distribution name candidate is `trustplane-auth-sdk`.
+
+The import module is `trustplane_auth`:
+
+```python
+from trustplane_auth import body_sha256, build_request, sign_request
+```
+
+The package version remains `0.0.0` until the release workflow is introduced.
+
+PyPI trusted publishing is planned in a follow-up.
+
+## Build Request Example
+
+```python
+from trustplane_auth import SOFTWARE_KEY_BINDING, Header, build_request
+
+material = build_request(
+    method="POST",
+    scheme="https",
+    authority="orders.example",
+    path="/v1/orders",
+    audience="orders-api",
+    route_id="orders.create",
+    content_encoding="identity",
+    body=b'{"order_id":"ord_123","amount":"42.00"}',
+    headers=[
+        Header(name="Content-Type", value="application/json"),
+        Header(name="X-TrustPlane-Nonce", value="nonce-v1-001"),
+    ],
+    header_allow_list=["content-type", "x-trustplane-nonce"],
+    passport_jti="passport-v1-minimal-001",
+    nonce="nonce-v1-001",
+    issued_at_unix=1740000000,
+    key_binding=SOFTWARE_KEY_BINDING,
+)
+
+print(material.transcript_sha256)
+```
+
+## Signing Example
+
+Signing requires a real passport whose `cnf.key_binding` is `software` and whose `cnf.public_key_b64url` matches the Ed25519 private key.
+
+```python
+from pathlib import Path
+
+from trustplane_auth import Header, sign_request
+
+passport = "header.payload.signature"
+private_key_pem = Path("ed25519-private-key.pem").read_bytes()
+
+signed = sign_request(
+    request={
+        "method": "POST",
+        "scheme": "https",
+        "authority": "orders.example",
+        "path": "/v1/orders",
+        "route_id": "orders.create",
+        "content_encoding": "identity",
+        "body": b'{"order_id":"ord_123","amount":"42.00"}',
+        "headers": [
+            Header(name="Content-Type", value="application/json"),
+            Header(name="X-TrustPlane-Nonce", value="nonce-v1-001"),
+        ],
+        "header_allow_list": ["content-type", "x-trustplane-nonce"],
+        "nonce": "nonce-v1-001",
+    },
+    passport_token=passport,
+    private_key=private_key_pem,
+)
+
+headers = signed.headers
+```
+
+`sign_request` reads passport-bound fields from the passport and fails if caller-supplied consistency checks conflict. It does not infer or repair `aud`, `jti`, `iat`, `cnf.kid`, `cnf.key_binding`, or `cnf.public_key_b64url` from caller request inputs.
+
+## Conformance Posture
+
+`testdata/conformance/v1` contains public-safe contract vectors copied from the TrustPlane Auth reference. Tests assert exact canonical transcript lines, transcript SHA-256 values, and body SHA-256 values.
+
+## Security Rule
+
+This SDK signs only the verifier-rebuilt request transcript. Raw local signing is software-only and requires an Ed25519 private key whose public key exactly matches the passport `cnf.public_key_b64url` claim.

trustplane_auth_sdk-0.1.0rc1/SECURITY.md

@@ -0,0 +1,7 @@
+# Security
+
+Please report suspected vulnerabilities through the repository security advisory flow or the TrustPlane security contact used for project disclosures.
+
+Do not include private keys, bearer tokens, passports, or production request transcripts in public issues.
+
+This package currently supports only raw local Ed25519 software signing. It rejects non-software key bindings for local signing.