Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 36 additions & 8 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,10 @@ on:
permissions:
contents: read
jobs:
release:
build:
runs-on: ubuntu-latest
environment: pypi
outputs:
prerelease: ${{ steps.version.outputs.prerelease }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
- uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
Expand All @@ -21,14 +22,35 @@ jobs:
- name: Match release tag to package version
run: |
uv run python -c 'import os,tomllib; v=tomllib.load(open("pyproject.toml","rb"))["project"]["version"]; assert os.environ["GITHUB_REF_NAME"] == "v"+v'
- name: Detect pre-release version
id: version
run: |
uv run python -c 'import tomllib; from packaging.version import Version; v=tomllib.load(open("pyproject.toml","rb"))["project"]["version"]; print("prerelease=" + str(Version(v).is_prerelease).lower())' >> "$GITHUB_OUTPUT"
- run: uv run ruff check . && uv run mypy src examples && uv run pytest
- run: uv build
- name: Publish distributions
env:
UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
run: uv publish
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: distributions
path: dist/
if-no-files-found: error
publish:
needs: build
runs-on: ubuntu-latest
environment: pypi
permissions:
id-token: write
steps:
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
with:
name: distributions
path: dist/
- uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
with:
python-version: '3.11'
- run: python -m pip install uv==0.11.27
- run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/
github-release:
needs: release
needs: [build, publish]
runs-on: ubuntu-latest
permissions:
contents: write
Expand All @@ -37,4 +59,10 @@ jobs:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
RELEASE_TAG: ${{ github.ref_name }}
run: gh release create "$RELEASE_TAG" --generate-notes
PRERELEASE: ${{ needs.build.outputs.prerelease }}
run: |
if [ "$PRERELEASE" = false ]; then
gh release create "$RELEASE_TAG" --title "ThunderID Python SDK $RELEASE_TAG" --generate-notes
else
gh release create "$RELEASE_TAG" --title "ThunderID Python SDK $RELEASE_TAG" --generate-notes --prerelease
fi
22 changes: 11 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@

An async Python SDK for the ThunderID open-source IAM stack, supporting humans, AI agents, and machines. Requires Python 3.11 or later. This implementation targets [SDK specification 0.5](https://github.com/thunder-id/thunderid/blob/main/docs-internals/sdk-development/spec.md); platform omissions and current limitations are listed below.

Install from a checkout:
Install the pre-release from PyPI:

```sh
python -m pip install .
python -m pip install "thunderid>=0.0.1a1"
```

Use a registered confidential client with `client_credentials` enabled and permissions on the target resource server. Supply the deployment URL and client credentials through your application's secret configuration:
Expand Down Expand Up @@ -42,19 +42,19 @@ The default session store uses a native OS credential store and fails closed if

For browser sign-in, configure `after_sign_in_url` with a registered callback URL, call `await client.sign_in()`, open the returned `AuthorizationRequest.url`, then complete on the same live client with `await client.handle_redirect_callback(url)` or structured parameters, `await client.handle_redirect_callback(code=code, state=state)`. Use `error=error` with state for a denied authorization; do not mix a URL with structured fields. The SDK verifies PKCE/state and the ID token, then stores the session. `await client.get_access_token()` and `await client.get_obo_token(authorization=session)` refresh owned interactive tokens near expiry; `await client.sign_out()` attempts revocation and clears local state even if revocation fails, reporting the error.

[API reference](docs/reference.md) covers configuration, returned types, errors, delegation, and storage. [Security notes](docs/security.md) explain trust boundaries and deployment limits.
[API reference](https://github.com/thunder-id/python-sdks/blob/main/docs/reference.md) covers configuration, returned types, errors, delegation, and storage. [Security notes](https://github.com/thunder-id/python-sdks/blob/main/docs/security.md) explain trust boundaries and deployment limits.

## Runnable examples

Run `python examples/client_credentials.py` (or another example) after installation. All deployment URLs and client configuration come from environment variables. No example prints tokens. Token-exchange inputs and callback URLs use hidden prompts instead of storing bearer credentials in environment variables.
From a clone of the repository, run `python examples/client_credentials.py` (or another example) after installation. All deployment URLs and client configuration come from environment variables. No example prints tokens. Token-exchange inputs and callback URLs use hidden prompts instead of storing bearer credentials in environment variables.

| Example | Required environment and server setup |
| --- | --- |
| [Machine identity](examples/client_credentials.py) | `THUNDERID_BASE_URL`, `THUNDERID_CLIENT_ID`, `THUNDERID_CLIENT_SECRET`, `THUNDERID_CLIENT_AUTH_METHOD=client_secret_basic`; client-credentials grant enabled. Set `THUNDERID_RESOURCE` and `THUNDERID_PERMISSION_SCOPES` for resource permissions. |
| [Interactive authorization](examples/interactive.py) | Base URL, client ID, and `THUNDERID_CALLBACK_URL`; authorization-code grant and callback registered. Uses the OS browser and a hidden callback URL prompt. Public clients omit secret/auth method. |
| [Embedded flow](examples/embedded.py) | HTTPS base URL, `THUNDERID_APPLICATION_ID`; an application with an authentication flow. Enter configured action/field identifiers and JSON input values at prompts. |
| [Explicit token exchange](examples/token_exchange.py) | Base URL, client ID/authentication; token exchange enabled and subject/actor accepted by server policy. Supply subject/actor tokens through hidden prompts. |
| [CIBA approval](examples/ciba.py) | Base URL, authenticated client, `THUNDERID_LOGIN_HINT`; poll-mode CIBA enabled and a working approval channel. Optional `THUNDERID_BINDING_MESSAGE`, `THUNDERID_CIBA_TIMEOUT`. |
| [Machine identity](https://github.com/thunder-id/python-sdks/blob/main/examples/client_credentials.py) | `THUNDERID_BASE_URL`, `THUNDERID_CLIENT_ID`, `THUNDERID_CLIENT_SECRET`, `THUNDERID_CLIENT_AUTH_METHOD=client_secret_basic`; client-credentials grant enabled. Set `THUNDERID_RESOURCE` and `THUNDERID_PERMISSION_SCOPES` for resource permissions. |
| [Interactive authorization](https://github.com/thunder-id/python-sdks/blob/main/examples/interactive.py) | Base URL, client ID, and `THUNDERID_CALLBACK_URL`; authorization-code grant and callback registered. Uses the OS browser and a hidden callback URL prompt. Public clients omit secret/auth method. |
| [Embedded flow](https://github.com/thunder-id/python-sdks/blob/main/examples/embedded.py) | HTTPS base URL, `THUNDERID_APPLICATION_ID`; an application with an authentication flow. Enter configured action/field identifiers and JSON input values at prompts. |
| [Explicit token exchange](https://github.com/thunder-id/python-sdks/blob/main/examples/token_exchange.py) | Base URL, client ID/authentication; token exchange enabled and subject/actor accepted by server policy. Supply subject/actor tokens through hidden prompts. |
| [CIBA approval](https://github.com/thunder-id/python-sdks/blob/main/examples/ciba.py) | Base URL, authenticated client, `THUNDERID_LOGIN_HINT`; poll-mode CIBA enabled and a working approval channel. Optional `THUNDERID_BINDING_MESSAGE`, `THUNDERID_CIBA_TIMEOUT`. |

Optional shared settings: `THUNDERID_CA_FILE` for a trusted CA bundle, `THUNDERID_SCOPES` for interactive scopes (default `openid`), and `THUNDERID_MEMORY_STORAGE=1` to explicitly opt into process-only sample storage. Permission scopes are space separated. The CIBA example always includes `openid`. Keep secrets out of shell history, committed files, and logs.

Expand All @@ -75,7 +75,7 @@ uv run pytest
uv build
```

Tests use mock HTTP transport and run offline. Real-server coverage and any environment requirements are recorded in [tests/e2e/README.md](tests/e2e/README.md). Follow [AGENTS.md](AGENTS.md) when contributing. Design: [discussion 5877](https://github.com/thunder-id/thunderid/discussions/5877); tracking issue: [2530](https://github.com/thunder-id/thunderid/issues/2530).
Tests use mock HTTP transport and run offline. Real-server coverage and any environment requirements are recorded in [tests/e2e/README.md](https://github.com/thunder-id/python-sdks/blob/main/tests/e2e/README.md). Follow [AGENTS.md](https://github.com/thunder-id/python-sdks/blob/main/AGENTS.md) when contributing. Design: [discussion 5877](https://github.com/thunder-id/thunderid/discussions/5877); tracking issue: [2530](https://github.com/thunder-id/thunderid/issues/2530).

## Contributing

Expand All @@ -85,4 +85,4 @@ For code contributions, follow [Contributing Code](https://thunderid.dev/communi

## License

This project is licensed under the [Apache License 2.0](LICENSE).
This project is licensed under the [Apache License 2.0](https://github.com/thunder-id/python-sdks/blob/main/LICENSE).
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ build-backend = "hatchling.build"

[project]
name = "thunderid"
version = "0.1.0"
version = "0.0.1a1"
description = "Async Python client for the ThunderID open-source IAM stack"
authors = [{name = "The ThunderID Authors"}]
keywords = ["thunderid", "iam", "oauth2", "openid-connect", "authentication", "ai-agents", "asyncio"]
Expand Down
2 changes: 1 addition & 1 deletion tests/e2e/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,4 @@ Generated settings, credentials, server logs, and databases stay under ignored `

The tests exercise actual HTTP endpoints using the SDK. A Gate-equivalent test driver completes server-described flow actions through the Flow API using action identifiers. This verifies server protocol integration, not browser UI rendering. The CLI examples are separately typechecked and compiled.

Repository setup is still required before releases: configure the protected `pypi` environment and its `PYPI_TOKEN` secret, reserve the package name, and make checks/parity required in branch protection. No package has been published by this implementation.
Releases publish to PyPI through Trusted Publishing, so no token is stored. Before the first release, register a PyPI pending publisher for project `thunderid` (owner `thunder-id`, repository `python-sdks`, workflow `release.yml`, environment `pypi`), create the `pypi` environment with required reviewers and deployments limited to `v*` tags, and make checks/parity required in branch protection.
2 changes: 1 addition & 1 deletion uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading