authplane-sdk 0.1.0__tar.gz

authplane_sdk-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+*   @AuthPlane/authplane-eng

authplane_sdk-0.1.0/.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,68 @@
+---
+name: Bug Report
+about: Report a bug in the Authplane Python SDK or an adapter
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Description
+
+A clear description of the bug.
+
+## Affected Package
+
+- [ ] `authplane-sdk`
+- [ ] `authplane-mcp`
+- [ ] `authplane-fastmcp`
+
+## Steps to Reproduce
+
+1. Install package(s) ...
+2. Configure / call ...
+3. Observe ...
+
+Minimal reproducible code snippet:
+
+```python
+# paste here
+```
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include exception traceback, HTTP status codes, and relevant log output.
+
+## Environment
+
+- **Package version:** (e.g., `authplane-sdk==1.2.3`)
+- **Python version:** (`python --version`)
+- **OS:** (e.g., Ubuntu 22.04, macOS 14)
+- **Framework (if adapter):** (e.g., FastAPI 0.115, FastMCP 2.x, MCP SDK 1.27)
+- **Authplane `authserver` version / issuer:** (if relevant)
+
+## Configuration
+
+Relevant SDK configuration (redact secrets):
+
+```python
+# paste here
+```
+
+## Logs
+
+<details>
+<summary>Relevant logs</summary>
+
+```
+(paste relevant logs here — redact any sensitive data, especially tokens)
+```
+
+</details>
+
+## Additional Context
+
+Any other relevant information.

authplane_sdk-0.1.0/.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,38 @@
+---
+name: Feature Request
+about: Suggest a new feature for the Authplane Python SDK or an adapter
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Affected Package
+
+- [ ] `authplane-sdk`
+- [ ] `authplane-mcp`
+- [ ] `authplane-fastmcp`
+- [ ] New package
+
+## Problem
+
+Describe the problem this feature would solve. What are you trying to do that you can't do today?
+
+## Proposed Solution
+
+Describe your proposed solution. How should this work? Include a rough API sketch if possible:
+
+```python
+# example usage
+```
+
+## Alternatives Considered
+
+What alternatives have you considered? Why is this approach better?
+
+## Use Case
+
+Describe the use case. Who benefits from this feature? Is this blocking integration with a specific framework or service?
+
+## Additional Context
+
+Any other relevant information, links to RFCs or specs, or examples from other projects.

authplane_sdk-0.1.0/.github/ISSUE_TEMPLATE/mcp-compatibility.md

@@ -0,0 +1,76 @@
+---
+name: MCP Compatibility Report
+about: Report compatibility of an MCP client or server with the Authplane Python adapters
+title: "[Compat] <Client or Server> <Version>"
+labels: compatibility, mcp
+assignees: ""
+---
+
+## Adapter
+
+- [ ] `authplane-mcp` (official MCP Python SDK adapter)
+- [ ] `authplane-fastmcp` (FastMCP adapter)
+
+## MCP Library Version
+
+- **Library:** (e.g., `mcp`, `fastmcp`)
+- **Version:**
+- **Transport:** (e.g., streamable-http, stdio)
+
+## MCP Client (if reporting a client-side issue)
+
+- **Client:** (e.g., Claude Code, MCP Inspector, Cursor)
+- **Version:**
+- **Platform:** (macOS / Linux / Windows)
+
+## Authplane SDK Version
+
+- `authplane-sdk`:
+- `authplane-mcp` / `authplane-fastmcp`:
+- `authserver` (issuer):
+
+## Description
+
+Brief summary of the compatibility observation.
+
+## Compatibility Scenarios
+
+Check each that was tested. Mark pass / fail / skip.
+
+- [ ] **JWT validation** — protected tool accepts valid bearer token
+- [ ] **Scope enforcement** — tool-specific scope required and checked
+- [ ] **DPoP-bound tokens** — proof-of-possession verified end-to-end (if applicable)
+- [ ] **Token refresh** — client refreshes without losing session
+- [ ] **Metadata discovery** — adapter surfaces `WWW-Authenticate` / protected-resource metadata correctly
+- [ ] **Error handling** — expired, revoked, malformed tokens produce the expected error shape
+
+## Reproduction Steps
+
+1. Install adapter ...
+2. Configure MCP server with Authplane middleware ...
+3. Connect client ...
+4. Observe results
+
+## Logs
+
+<details>
+<summary>Server logs (adapter)</summary>
+
+```
+(paste relevant logs here)
+```
+
+</details>
+
+<details>
+<summary>Client logs</summary>
+
+```
+(paste relevant logs here)
+```
+
+</details>
+
+## Additional Context
+
+Screenshots, network traces, spec references, or upstream issues.

authplane_sdk-0.1.0/.github/dependabot.yml

@@ -0,0 +1,70 @@
+version: 2
+
+updates:
+  # Python SDK (root)
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    labels:
+      - dependencies
+      - python
+    commit-message:
+      prefix: "deps"
+    open-pull-requests-limit: 10
+    groups:
+      pip-all:
+        patterns:
+          - "*"
+
+  # Python MCP adapter
+  - package-ecosystem: pip
+    directory: /authplane-mcp
+    schedule:
+      interval: weekly
+      day: monday
+    labels:
+      - dependencies
+      - python
+    commit-message:
+      prefix: "deps"
+    open-pull-requests-limit: 10
+    groups:
+      pip-all:
+        patterns:
+          - "*"
+
+  # Python FastMCP adapter
+  - package-ecosystem: pip
+    directory: /authplane-fastmcp
+    schedule:
+      interval: weekly
+      day: monday
+    labels:
+      - dependencies
+      - python
+    commit-message:
+      prefix: "deps"
+    open-pull-requests-limit: 10
+    groups:
+      pip-all:
+        patterns:
+          - "*"
+
+  # GitHub Actions
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    labels:
+      - dependencies
+      - ci
+    commit-message:
+      prefix: "ci"
+    open-pull-requests-limit: 5
+    groups:
+      actions-all:
+        patterns:
+          - "*"

authplane_sdk-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,35 @@
+## Summary
+
+Brief description of what this PR does and why.
+
+## Linked Issue
+
+<!-- e.g., Fixes #123 -->
+
+## Changes
+
+-
+
+## Affected Packages
+
+- [ ] `authplane-sdk` (root)
+- [ ] `authplane-mcp`
+- [ ] `authplane-fastmcp`
+- [ ] None (infra / docs / CI only)
+
+## Test Plan
+
+How was this tested? Include relevant test names or manual verification steps.
+
+## Checklist
+
+- [ ] `ruff check .` passes
+- [ ] `ruff format --check .` passes
+- [ ] `pyright` passes (SDK root)
+- [ ] `pytest` passes for affected packages
+- [ ] Coverage unchanged or improved (≥ 80%)
+- [ ] Tests added for new functionality
+- [ ] Documentation updated (if applicable)
+- [ ] `CHANGELOG.md` entry added under `[Unreleased]` (if user-facing)
+- [ ] New workflow actions are SHA-pinned (`pinact run` after changes)
+- [ ] No token values, secrets, or key material in logs or test fixtures

authplane_sdk-0.1.0/.github/workflows/backport-fixes.yml

@@ -0,0 +1,125 @@
+name: Backport fixes to default branch
+
+# Thin wrapper around scripts/backport-fixes.sh for maintainers who
+# prefer dispatching from the Actions UI. Behavior:
+#
+#   - Happy path (no conflicts): runs the script, pushes the backport
+#     branch, opens a PR against the target.
+#   - Any conflict: cherry-pick fails, the workflow fails loudly. Re-run
+#     the script locally to finish:
+#         scripts/backport-fixes.sh --from <fromBranch> --to <toBranch>
+#     and resolve conflicts via git's native cherry-pick state machine.
+#
+# fromBranch can be a branch (release/v*, hotfix/v*) or a tag (vX.Y.Z).
+# After the release workflow runs, the release branch is deleted — use the
+# tag as the fromBranch instead.
+
+on:
+  workflow_dispatch:
+    inputs:
+      fromBranch:
+        description: 'Source ref on origin (branch or tag, e.g. release/v0.6.0, hotfix/v0.5.1, or v0.6.0). Do not include origin/.'
+        required: true
+        type: string
+      toBranch:
+        description: 'Target branch on origin. Leave empty to use the repository default branch.'
+        required: false
+        type: string
+        default: ''
+
+concurrency:
+  group: backport-${{ inputs.fromBranch }}-to-${{ inputs.toBranch }}
+  cancel-in-progress: false
+
+jobs:
+  backport:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Resolve target branch
+        id: target
+        run: |
+          to="${{ inputs.toBranch }}"
+          if [[ -z "$to" ]]; then
+            to="${{ github.event.repository.default_branch }}"
+          fi
+          echo "to=$to" >> "$GITHUB_OUTPUT"
+
+      - name: Check out repo with full history
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Configure git author
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Run backport script
+        id: run
+        run: |
+          ./scripts/backport-fixes.sh \
+            --from "${{ inputs.fromBranch }}" \
+            --to   "${{ steps.target.outputs.to }}"
+          echo "branch=$(git rev-parse --abbrev-ref HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Push backport branch
+        if: startsWith(steps.run.outputs.branch, 'backport/')
+        run: |
+          git push origin "${{ steps.run.outputs.branch }}"
+
+      - name: Open pull request
+        if: startsWith(steps.run.outputs.branch, 'backport/')
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          from="${{ inputs.fromBranch }}"
+          to="${{ steps.target.outputs.to }}"
+          branch="${{ steps.run.outputs.branch }}"
+          title="chore: backport from $from to $to"
+          body=$(cat <<EOF
+          Automated backport from \`$from\` to \`$to\`.
+
+          All candidate commits applied cleanly. If the set looks wrong,
+          curate this branch locally:
+
+          \`\`\`
+          git fetch origin
+          git checkout $branch
+          git rebase -i origin/$to   # drop commits you don't want
+          git push --force-with-lease
+          \`\`\`
+
+          **Merge with "Rebase and merge"** (not squash) — preserves
+          per-commit \`-x\` attribution on \`$to\`.
+          EOF
+          )
+          gh pr create \
+            --base "$to" \
+            --head "$branch" \
+            --title "$title" \
+            --body "$body"
+
+      - name: Nothing to backport notice
+        if: steps.run.outputs.branch != '' && !startsWith(steps.run.outputs.branch, 'backport/')
+        run: |
+          echo "::notice::Nothing to backport — all commits on origin/${{ inputs.fromBranch }} are already present on origin/${{ steps.target.outputs.to }}."
+
+      - name: Conflict guidance (on failure)
+        if: failure()
+        run: |
+          {
+            echo "### Backport failed"
+            echo ""
+            echo "At least one cherry-pick conflicted. Finish manually:"
+            echo ""
+            echo '```'
+            echo "scripts/backport-fixes.sh \\"
+            echo "  --from ${{ inputs.fromBranch }} \\"
+            echo "  --to   ${{ steps.target.outputs.to }}"
+            echo '```'
+            echo ""
+            echo "Then resolve conflicts and \`git cherry-pick --continue\` (or \`--skip\` / \`--abort\`)."
+          } >> "$GITHUB_STEP_SUMMARY"

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

@@ -0,0 +1,101 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        package:
+          - root
+          - authplane-mcp
+          - authplane-fastmcp
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      # AuthPlane/conformance is the public sibling repo carrying the shared
+      # oauth-sdk-conformance-catalog.yaml. Without it, conformance-tests
+      # cannot run.
+      - name: Check out shared conformance catalog
+        if: matrix.package == 'root'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: AuthPlane/conformance
+          path: conformance
+          fetch-depth: 1
+
+      - name: Setup Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Install package dependencies
+        run: |
+          if [ "${{ matrix.package }}" = "root" ]; then
+            pip install -e ".[dev]"
+          else
+            # Adapters depend on authplane; install local SDK package first.
+            pip install -e .
+            pip install -e "${{ matrix.package }}[dev]"
+          fi
+
+      - name: Ruff check
+        run: |
+          if [ "${{ matrix.package }}" = "root" ]; then
+            ruff check .
+          else
+            ruff check "${{ matrix.package }}"
+          fi
+
+      - name: Ruff format check
+        run: |
+          if [ "${{ matrix.package }}" = "root" ]; then
+            ruff format --check .
+          else
+            ruff format --check "${{ matrix.package }}"
+          fi
+
+      - name: Pyright (SDK only)
+        if: matrix.package == 'root'
+        run: pyright
+
+      - name: Test and coverage
+        env:
+          CONFORMANCE_CATALOG_PATH: ${{ github.workspace }}/conformance/oauth-sdk-conformance-catalog.yaml
+        run: |
+          if [ "${{ matrix.package }}" = "root" ]; then
+            coverage run -m pytest tests conformance-tests && coverage report
+          else
+            cd "${{ matrix.package }}"
+            coverage run -m pytest tests && coverage report
+          fi
+
+      - name: Build package artifacts
+        run: |
+          if [ "${{ matrix.package }}" = "root" ]; then
+            python -m build
+          else
+            cd "${{ matrix.package }}"
+            python -m build
+          fi
+
+      - name: Validate package metadata
+        run: |
+          if [ "${{ matrix.package }}" = "root" ]; then
+            twine check dist/*
+          else
+            twine check "${{ matrix.package }}/dist/*"
+          fi