sillo-oauth 0.1.0__tar.gz

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

@@ -0,0 +1,103 @@
+name: Release on Tag
+
+on:
+  push:
+    tags:
+      - 'oauth-v*'   # e.g. oauth-v0.1.0
+
+jobs:
+  release:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write   # OIDC, for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          TAG="${{ github.ref_name }}"
+          VERSION="${TAG#oauth-v}"
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "📦 Releasing sillo-oauth v$VERSION"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      # The install script has moved between ~/.cargo/bin and ~/.local/bin
+      # across uv versions. Add both so the PATH does not depend on which
+      # installer layout ships today.
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      # PyPI takes the version from the package, not the tag. Without this a
+      # tag of oauth-v0.2.0 against a pyproject still saying 0.1.0 publishes
+      # 0.1.0 and reports success, and the version it claims to have released
+      # is one that does not exist.
+      - name: The tag and the package must agree
+        run: |
+          TAG_VERSION="${{ steps.version.outputs.version }}"
+          PKG_VERSION=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag says $TAG_VERSION, pyproject.toml says $PKG_VERSION."
+            exit 1
+          fi
+          echo "both say $PKG_VERSION"
+
+      - name: Clean old builds
+        run: rm -rf dist build ./*.egg-info
+
+      - name: Setup virtual environment
+        run: uv venv
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]"
+
+      # A release that skips the suite is a release nobody checked. The tests
+      # need no network and no credentials, so there is no excuse for not
+      # running them here.
+      - name: Run tests
+        run: uv run pytest tests/ -q --tb=short
+
+      - name: Build the package
+        run: uv build
+
+      # py.typed has no extension, so it falls outside hatchling's default
+      # include rules and has already been missing from a wheel once. A green
+      # test run would not notice.
+      - name: The wheel must carry py.typed
+        run: |
+          python - <<'PY'
+          import glob, sys, zipfile
+          wheel = glob.glob("dist/*.whl")[0]
+          if "sillo_oauth/py.typed" not in zipfile.ZipFile(wheel).namelist():
+              sys.exit(f"::error::{wheel} ships no py.typed")
+          print(f"{wheel} carries py.typed")
+          PY
+
+      - name: Check metadata
+        run: uvx twine check dist/*
+
+      # Prefers OIDC trusted publishing (the id-token permission above); falls
+      # back to an API token when the PYPI_TOKEN secret is set. Passing an empty
+      # --token is a hard failure, so the secret must not be forwarded blindly.
+      - name: Publish to PyPI
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          if [ -n "$PYPI_TOKEN" ]; then
+            uv publish --token "$PYPI_TOKEN"
+          else
+            uv publish
+          fi

sillo_oauth-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,88 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # The install script has moved between ~/.cargo/bin and ~/.local/bin
+      # across uv versions. Add both so the PATH does not depend on which
+      # installer layout ships today.
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Install
+        run: |
+          uv venv
+          uv pip install -e ".[dev]" ruff mypy
+
+      # No `|| true` on any of these. The suite needs no network and no
+      # credentials, so a failure here is a real failure and gating on it is
+      # the whole point of running it.
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run mypy sillo_oauth/
+
+      - name: Test
+        run: uv run pytest tests/ -q
+
+  packaging:
+    name: Wheel contents
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Build
+        run: uv build --wheel
+
+      # py.typed has no extension, so it falls outside hatchling's default
+      # include rules. It has already been dropped from a wheel once; this
+      # keeps the Typing :: Typed classifier honest.
+      - name: The wheel must carry py.typed
+        run: |
+          python - <<'PY'
+          import glob, sys, zipfile
+          wheel = glob.glob("dist/*.whl")[0]
+          names = zipfile.ZipFile(wheel).namelist()
+          if "sillo_oauth/py.typed" not in names:
+              sys.exit(f"::error::{wheel} ships no py.typed")
+          print(f"{wheel} carries py.typed")
+          PY

sillo_oauth-0.1.0/.gitignore

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

sillo_oauth-0.1.0/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-08-08
+
+First release. The package was written and then reviewed in one sitting, so
+the fixes below are against unreleased commits rather than against anything
+anyone installed — they are kept because two of them are worth a reader's
+attention, and because the reasoning is the useful part.
+
+Requires `sillo-framework>=0.0.1a15`. That is still an alpha, so this release
+is only as stable as the framework under it; the API here is what is being
+called stable at 0.1.0, not the ground it stands on.
+
+### Added
+
+- `refresh_tokens()`, and `OAuthProvider.refresh_request_data()` as the
+  provider-level hook. `OAuthTokens.refresh_token` had been captured since the
+  first commit with no way to spend it. When a provider does not rotate the
+  refresh token — most reuse it and omit it from the response — the one passed
+  in is carried onto the result, so a caller that stores
+  `tokens.refresh_token` cannot overwrite a working token with `None`.
+- `exchange(..., state_value=...)`, for applications that keep the state in the
+  session or a cache rather than the cookie.
+- `token_headers` and `userinfo_headers` constructor arguments, merged over the
+  class defaults so adding one header does not mean restating the `Accept` that
+  several providers need in order to answer with JSON.
+- `GithubOAuthProvider(emails_endpoint=...)`.
+- `py.typed`, so the annotations are visible to downstream type checkers.
+- CI across Python 3.10–3.13, gating on tests, `ruff check`, `ruff format` and
+  `mypy`, plus a packaging job that asserts the built wheel contains
+  `py.typed`.
+
+### Fixed
+
+- **Authorize parameters that the package manages are now refused instead of
+  overridden.** `extra_params` and `authorize_params` were merged *over* the
+  computed parameters, so `extra_params={"state": ...}` replaced the value the
+  cookie had just been signed against. At best every login failed as a
+  mismatch; at worst an attacker-chosen value was sent and the CSRF guarantee
+  quietly stopped holding. The same applied to `code_challenge` and PKCE.
+- **`OAuthTokens` no longer prints its credentials.** Every field on it is a
+  live token and the generated dataclass repr showed all of them, so
+  `logger.info("signed in %s", profile)` wrote a working access token to the
+  log, as did any traceback holding a profile in a frame.
+- **GitHub's emails endpoint follows `userinfo_endpoint`.** It was hardcoded to
+  `api.github.com`, so pointing the provider at a GitHub Enterprise host moved
+  only half the flow and sent an Enterprise access token to the public API.
+- **An endpoint's own query no longer duplicates a managed parameter.** A
+  configured `authorize_endpoint` carrying `state=` got ours appended after it,
+  producing a URL with the parameter twice and leaving the provider to choose.
+- **`expires_in` is read in whatever shape the provider sent.** The old guard
+  silently dropped every lifetime that was not a plain non-negative integer
+  literal, including the decimals and numeric strings that providers do send.
+  Negatives and booleans are still dropped deliberately.
+- Class-level header mappings are `MappingProxyType`. As plain dicts they were
+  shared by every instance, so mutating one to add a header to a single
+  provider changed every other provider of that type.
+- Two documented examples that would have failed if anyone ran them: the module
+  docstring set the cookie before the redirect, which sillo's `Responder`
+  cannot do, and the session example called `Session.pop()`, which does not
+  exist.
+
+### Security notes
+
+Two of the fixes above would have been advisories had they shipped, and are
+called out here for anyone auditing the history:
+
+- `extra_params` could override `state` and `code_challenge`, disarming CSRF
+  and PKCE.
+- `OAuthTokens`' repr printed live credentials into logs and tracebacks.
+
+[0.1.0]: https://github.com/sillohq/oauth/releases/tag/oauth-v0.1.0

sillo_oauth-0.1.0/LICENSE

@@ -0,0 +1,27 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-present, sillo-Labs OSS.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sillo_oauth-0.1.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: sillo-oauth
+Version: 0.1.0
+Summary: OAuth 2.0 / OpenID Connect login for Sillo — plain functions, no router, no middleware.
+Project-URL: Homepage, https://github.com/sillohq/oauth
+Project-URL: Repository, https://github.com/sillohq/oauth
+Project-URL: Documentation, https://sillolabs.com
+Project-URL: Issues, https://github.com/sillohq/oauth/issues
+Author-email: Chidebele Dunamis <techwithdunamix@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: asgi,github,google,oauth,oauth2,oidc,sillo,sso
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+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 :: Internet :: WWW/HTTP :: Session
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<0.29.0,>=0.23.3
+Requires-Dist: sillo-framework>=0.0.1a15
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.25.3; extra == 'dev'
+Requires-Dist: pytest>=8.3.5; extra == 'dev'
+Requires-Dist: sillo-framework[jwt,record]>=0.0.1a15; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sillo-oauth
+
+[![Test](https://github.com/sillohq/oauth/actions/workflows/test.yml/badge.svg)](https://github.com/sillohq/oauth/actions/workflows/test.yml)
+
+OAuth 2.0 and OpenID Connect login for [Sillo](https://github.com/sillohq/core).
+
+Two functions and a provider object. Neither function takes a response, builds
+one, or registers a route — so the routes, the error handling, and the decision
+of what a login *means* stay in your application.
+
+```bash
+pip install sillo-oauth
+```
+
+## The whole API
+
+```python
+from sillo_oauth import GoogleOAuthProvider, authorize_url, exchange, OAuthError
+
+google = GoogleOAuthProvider(
+    client_id=...,
+    client_secret=...,
+    state_secret=...,  # signs the state cookie; your own key
+    redirect_uri="https://example.com/auth/google/callback",
+)
+
+
+@app.get("/auth/google/redirect")
+async def start(request, response):
+    authorize = authorize_url(google)
+    return response.redirect(authorize.url).set_cookie(**authorize.cookie_kwargs())
+
+
+@app.get("/auth/google/callback")
+async def finish(request, response):
+    try:
+        profile = await exchange(google, request)
+    except OAuthError as exc:
+        return response.redirect(f"/login?error={exc.code}")
+
+    user = await User.objects.get_or_create_from_oauth("google", profile)
+    login(request, user)
+    return response.redirect(profile.return_to or "/")
+```
+
+That is the entire integration. `authorize_url` is pure — no request, no I/O —
+and returns a URL plus the state you need to store. `exchange` reads the
+callback request and returns a verified `OAuthProfile`. Nothing else is
+implied.
+
+> **Local development over `http://`** needs `cookie_kwargs(secure=False)`.
+> Otherwise the browser accepts the `Secure` cookie and never sends it back,
+> and every callback fails as a state mismatch.
+
+## What it deliberately does not do
+
+Turning a verified external identity into a logged-in user is your
+application's decision, not this package's. So there is no `on_success` hook,
+no user model, no session handling — just the four lines after `exchange`:
+
+```python
+# a server-rendered app
+login(request, user)
+return response.redirect("/dashboard")
+
+# an SPA or mobile client
+token = create_jwt({"id": user.id}, SECRET)
+return response.json({"access_token": token})
+
+# linking a provider to the user who is already signed in
+await OAuthIdentity.objects.link(request.user, "github", profile.subject)
+
+# nothing at all — just prove the address
+return response.json({"verified_email": profile.email})
+```
+
+The same two functions serve all of them.
+
+## Providers
+
+`GoogleOAuthProvider`, `GithubOAuthProvider`, `DiscordOAuthProvider` and
+`MicrosoftOAuthProvider` ship with endpoints, scopes and profile mapping
+filled in. Every one of those is overridable per instance.
+
+Anything else uses `OAuthProvider` directly:
+
+```python
+gitlab = OAuthProvider(
+    name="gitlab",
+    client_id=...,
+    client_secret=...,
+    state_secret=...,
+    authorize_endpoint="https://gitlab.com/oauth/authorize",
+    token_endpoint="https://gitlab.com/oauth/token",
+    userinfo_endpoint="https://gitlab.com/api/v4/user",
+    scopes=["read_user"],
+)
+```
+
+Self-hosted installations override the endpoints, and everything derived from
+them follows — pointing GitHub at an Enterprise host also moves the address
+lookup it falls back to:
+
+```python
+github = GithubOAuthProvider(
+    ...,
+    userinfo_endpoint="https://github.acme-corp.test/api/v3/user",
+)
+```
+
+Extra headers are merged over the provider's defaults, so adding one does not
+mean restating the rest:
+
+```python
+acme = OAuthProvider(..., userinfo_headers={"X-Tenant": "acme"})
+```
+
+To map a provider's fields yourself, pass `profile_mapper` or subclass and
+override `map_profile`:
+
+```python
+acme = OAuthProvider(
+    ...,
+    profile_mapper=lambda raw: {
+        "subject": raw["employee_number"],
+        "email": raw["work_email"],
+        "name": raw["full_name"],
+    },
+)
+```
+
+## `OAuthProfile`
+
+```python
+profile.provider  # "google"
+profile.subject  # stable provider-side id — the only safe account key
+profile.key  # "google:112233" — unique across providers
+profile.email
+profile.email_verified  # False also means "the provider did not say"
+profile.name
+profile.username
+profile.avatar_url
+profile.raw  # the untouched userinfo payload
+profile.tokens  # access/refresh tokens, for calling the provider later
+profile.return_to  # whatever you passed to authorize_url(return_to=...)
+```
+
+Key accounts on `subject`, never on `email`: addresses get reassigned, and an
+unverified one is an account-takeover vector.
+
+## Errors
+
+Every failure raises an `OAuthError` subclass carrying a stable, URL-safe
+`.code`, so one `except` is enough and codes can go straight into a redirect.
+
+| `.code` | Raised when |
+|---|---|
+| `denied` | The person declined consent. Not a fault — send them back to the login page. |
+| `provider_error` | The provider reported some other `error` parameter. |
+| `state_mismatch` | The callback does not match a redirect this server issued: no cookie, no `state`, a forged or tampered cookie, or one minted for another provider. |
+| `state_expired` | Genuine state, but too old. Worth a "that took too long, try again". |
+| `exchange_failed` | The provider would not trade the code for a token. |
+| `profile_failed` | A token was issued but no usable profile came back. |
+| `provider_misconfigured` | Programming error — a missing secret, redirect URI, or endpoint. |
+
+## Security
+
+* **State is signed, not stored.** No session store, no database, no sticky
+  routing — the CSRF token rides in an HMAC-signed cookie carrying an expiry
+  and the provider name, so a cookie minted for one provider cannot complete
+  another's callback.
+* **PKCE verifiers are derived, never stored.** The verifier is recomputed at
+  exchange time as `HMAC(state_secret, state)`. Putting it in the cookie would
+  have placed a secret somewhere readable; keeping it server-side would have
+  reintroduced the state store. The provider only ever sees the S256
+  challenge.
+* **State is verified before anything is sent to the provider**, so a forged
+  callback cannot make your server issue a token request.
+* Reserved parameters (`state`, `code_challenge`, `client_id`, …) cannot be
+  overridden through `extra_params`. Supplying one raises rather than being
+  ignored, because an application that believes it is setting `state` and
+  silently is not has a security expectation the code no longer meets.
+* **Tokens are redacted from reprs.** `logger.info("signed in %s", profile)` is
+  an ordinary line to write, and an error tracker collects tracebacks holding
+  profiles in frames. Neither leaks a credential; attribute access is
+  unaffected.
+
+`state_secret` is unrelated to `client_secret`: it protects your own cookies,
+not your relationship with the provider. Any high-entropy application key
+works, and one can be shared across providers.
+
+## Lower-level entry points
+
+`exchange(provider, request)` is a convenience over functions that take no
+request at all, for callers whose callback did not arrive as a Sillo request —
+a worker, a CLI, a test:
+
+```python
+profile = await complete(provider, code=..., state=..., cookie_value=...)
+tokens = await exchange_code(provider, code=..., verifier=...)
+profile = await fetch_profile(provider, tokens)
+tokens = await refresh_tokens(provider, refresh_token=...)
+```
+
+Storing state somewhere other than a cookie works the same way — hand the
+stored value back explicitly:
+
+```python
+# at the redirect step
+request.session["oauth_state"] = authorize.cookie_value
+
+# at the callback — sillo's Session has get/delete, not pop
+stored = request.session.get("oauth_state")
+request.session.delete("oauth_state")
+profile = await exchange(google, request, state_value=stored)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest              # 240+ tests, no network
+ruff check .
+ruff format --check .
+mypy sillo_oauth/
+```
+
+The suite never touches the network and never needs real credentials. Provider
+responses are canned through an injected `httpx` transport, and an autouse
+fixture breaks the real transport so a test that forgets a stub fails loudly
+instead of reaching out to Google.
+
+## Licence
+
+BSD-3-Clause.