fulla-oauth2 1.0.0__tar.gz

fulla_oauth2-1.0.0/.gitignore

@@ -0,0 +1,133 @@
+
+# Agent Skill Reports
+*.log
+*_report.md
+fix_run.md
+review_config_verification.md
+__pycache__/
+
+# Git Worktrees
+.worktrees/
+worktrees/
+
+# IDE & Envs
+# .vscode/ - 部分配置文件需要提交到版本控制
+.vscode/settings.local.json
+.vscode/tasks.local.json
+.vscode/launch.local.json
+.vscode/.intellicache/
+.venv/
+**/.venv/
+
+# Claude Code Settings
+.claude/settings.local.json
+
+# Sensitive Data
+cookies.txt
+
+# Sensitive Configuration Files
+.env
+.env.local
+
+# Benchmark generated token pools (contain raw token secrets)
+benchmarks/fulla/lib/generated/
+.env.*.local
+.env.docker
+.mcp.json
+*.pem
+*.key
+*.cert
+*.crt
+secrets/
+credentials/
+# Frontend runtime config with production credentials
+frontends/user/.env
+frontends/user/public/config.json
+# Deploy secrets
+deploy/nginx/ssl/*.pem
+deploy/keys/*.pem
+
+# Release Files
+Release_v1.0.0.zip
+
+# Temporary Outputs
+tmp_output/
+
+# Test Runtime Files
+test_config_env_runtime.json
+test-results/
+**/test-results/
+**/playwright-report/
+**/blob-report/
+**/playwright/.cache/
+*_test_logs/
+*.log.files/
+
+# Runtime directories (created by Drogon at startup)
+**/logs/
+# Exception: admin console source directory named "logs" (page component)
+!OAuth2Admin/src/pages/logs/
+!OAuth2Admin/src/pages/logs/**
+**/uploads/
+
+# Bug Fix Reports - local documentation only
+reports/
+
+# Build artifacts
+build/
+build-*/
+
+# Code coverage reports (gcov output via gcovr; local-only, never tracked)
+coverage-report/
+coverage-summary.txt
+coverage-summary.json
+CMakeUserPresets.json
+libs/storage-postgres/models_backup/
+
+# Cross-project patterns
+**/node_modules/
+**/dist/
+**/__pycache__/
+**/*.pyc
+
+# Kiro spec workflow scratch (commit messages, probes, etc.). Spec files
+# under .kiro/specs/ remain tracked.
+.kiro/tmp/
+
+build_log.txt
+ctest_output.txt
+
+test_admin.txt
+test_oauth2.txt
+build_p12.txt
+
+# Graphify knowledge graph (generated artifacts, local only)
+graphify-out/
+
+# Codegraph local index & runtime state
+.codegraph/
+
+# Superpowers SDD scratch (task briefs, reports, progress ledger)
+.superpowers/
+
+.playwright-mcp/
+.mimosa/
+
+# Client SDKs (clients/) local artifacts
+**/.pytest_cache/
+**/.ruff_cache/
+**/*.egg-info/
+clients/python/.venv/
+
+# ZCode per-session scratch (plans/tmp — same convention as .kiro/tmp/)
+.zcode/tmp/
+.zcode/plans/
+
+# AI-tool workspaces (local-only; .claude/ stays tracked as the single source
+# of truth for rules/skills — see docs/branding/repo-professionalization-audit.md)
+.qoder/
+.codebuddy/
+.kiro/
+.zcode/
+.workbuddy/
+frontends/user/scratch/scratch-output/

fulla_oauth2-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fulla_oauth2-1.0.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: fulla-oauth2
+Version: 1.0.0
+Summary: Python client SDK for Fulla, the embeddable C++ OAuth2/OIDC authorization server
+Project-URL: Homepage, https://github.com/voidvec/fulla
+Project-URL: Documentation, https://github.com/voidvec/fulla/tree/master/clients/python
+Project-URL: Repository, https://github.com/voidvec/fulla
+Author: Fulla contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authorization,client,fulla,oauth2,oidc,openid-connect,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: httpx<0.29.0,>=0.23.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Fulla Python Client
+
+Typed Python SDK for [Fulla](https://github.com/voidvec/fulla) — the embeddable
+C++ OAuth2/OIDC authorization server.
+
+- **Distribution name:** `fulla-oauth2` (the shorter `fulla` name on PyPI belongs to an
+  unrelated project)
+- **Import name:** `fulla`
+- **API surface:** generated from the server's single-source OpenAPI spec
+  (`apps/server/openapi.yaml`) with [openapi-python-client](https://github.com/openapi-generators/openapi-python-client)
+  0.29.0 — 78 operations, fully typed (`py.typed`), `attrs`-based models over `httpx`
+- **Auth layer:** handwritten (token lifecycle is too sensitive to template — see the
+  [design doc](../../docs/productization-evolution/in-progress/client-sdk-facility-design.md))
+
+```bash
+pip install fulla-oauth2
+```
+
+> Published to PyPI since v1.3.0 (release pipeline's `sdk-python` job). Prefer the released wheel; a
+> checkout install (`pip install clients/python`) still works for development.
+
+## Quickstart: machine-to-machine (client_credentials)
+
+```python
+from fulla import m2m_client
+from fulla.generated.api.o_auth_2 import post_oauth2_introspect
+from fulla.generated.models.post_oauth_2_introspect_body import PostOauth2IntrospectBody
+
+client = m2m_client(
+    "http://localhost:5555",
+    client_id="backend-svc",
+    client_secret="…",
+    scopes=["tokens:read"],
+)
+
+# Every request carries a valid Bearer token: fetched lazily, cached,
+# refreshed 30 s before expiry, force-refreshed once on a 401.
+result = post_oauth2_introspect.sync(
+    client=client, body=PostOauth2IntrospectBody(token=some_access_token)
+)
+print(result.active)
+
+# When done: closes BOTH the API client and the auth layer's token pool
+# (closing the generated client alone leaks the token connection pool).
+from fulla import close_m2m_client
+close_m2m_client(client)
+```
+
+Async is symmetric:
+
+```python
+from fulla import async_m2m_client
+
+client = async_m2m_client("http://localhost:5555", "backend-svc", "…", scopes=["tokens:read"])
+result = await post_oauth2_introspect.asyncio(client=client, body=body)
+```
+
+One-shot token fetch (scripts, benchmarks):
+
+```python
+from fulla import fetch_client_credentials_token
+
+token, expires_in = fetch_client_credentials_token(
+    "http://localhost:5555", "backend-svc", "…", ["tokens:read"]
+)
+```
+
+## Introspect / revoke (client Basic authentication)
+
+`/oauth2/introspect` and `/oauth2/revoke` authenticate the *calling client*, not a user bearer
+token (RFC 7662 §2.1). Use a client whose every request carries HTTP Basic — confidential
+clients must use Basic; the server rejects credentials in the body (F-017):
+
+```python
+from fulla import basic_auth_client
+
+client = basic_auth_client("http://localhost:5555", "backend-svc", "…")
+result = post_oauth2_introspect.sync(client=client, body=PostOauth2IntrospectBody(token=tok))
+```
+
+## Authorization-code flow (web apps, with PKCE)
+
+```python
+from fulla import AuthorizationCodeFlow, PkcePair
+
+flow = AuthorizationCodeFlow(
+    "http://localhost:5555", "my-client", "my-secret",
+    redirect_uri="https://my.app/callback", scopes=["openid", "profile"],
+)
+pkce = PkcePair.generate()
+authorize_url = flow.build_authorize_url(state=session_csrf, pkce=pkce)
+# → send the user's browser to authorize_url; Fulla redirects back with ?code=…&state=…
+# → VERIFY state, then:
+tokens = flow.exchange_code(code, pkce.verifier)
+# … later; Fulla rotates refresh tokens on every use (V008):
+tokens = flow.refresh(tokens.refresh_token)
+```
+
+## Generated API modules
+
+Everything under `fulla.generated` is the typed surface of the whole server API:
+
+```python
+from fulla.generated.api.open_id_connect import get_well_known_openid_configuration
+from fulla.generated.api.o_auth_2 import get_oauth2_userinfo, post_oauth2_token
+from fulla.generated.models.token_request import TokenRequest
+```
+
+Each endpoint module offers `sync`, `sync_detailed`, `asyncio`, `asyncio_detailed`. The
+`*_detailed` variants return status code + raw response alongside the parsed model.
+
+## Development
+
+```bash
+cd clients/python
+pip install -e ".[dev]"
+pytest                       # unit tests (in-process MockTransport, no server needed)
+
+# integration tests (needs a running full stack, see tests/integration/)
+FULLA_BASE_URL=http://127.0.0.1:5555 pytest tests/integration
+```
+
+Regenerating the committed `src/fulla/generated/` tree after an `openapi.yaml` change:
+
+```bash
+pip install openapi-python-client==0.29.0
+python tools/clients/regen_clients.py            # from the repo root
+```
+
+CI (`.github/workflows/clients-sdk.yml`) re-generates and diffs on every PR touching
+`clients/**` or the spec — committed generated code can never go stale.
+
+## Versioning
+
+The package version is locked to the server's `cmake/Version.cmake` (enforced by
+`tools/clients/regen_clients.py --version-only` at release time). Breaking HTTP API changes
+require a major bump on both sides (guarded by the `openapi-governance` oasdiff workflow).
+
+## Local network note
+
+If `go`/module proxies are unreachable from your network, the Go generator download mentioned
+in the regen docs needs a GOPROXY mirror (e.g. `GOPROXY=https://goproxy.cn,direct`). This only
+affects regenerating `clients/go` — installing and using this Python package is unaffected.

fulla_oauth2-1.0.0/README.md

@@ -0,0 +1,143 @@
+# Fulla Python Client
+
+Typed Python SDK for [Fulla](https://github.com/voidvec/fulla) — the embeddable
+C++ OAuth2/OIDC authorization server.
+
+- **Distribution name:** `fulla-oauth2` (the shorter `fulla` name on PyPI belongs to an
+  unrelated project)
+- **Import name:** `fulla`
+- **API surface:** generated from the server's single-source OpenAPI spec
+  (`apps/server/openapi.yaml`) with [openapi-python-client](https://github.com/openapi-generators/openapi-python-client)
+  0.29.0 — 78 operations, fully typed (`py.typed`), `attrs`-based models over `httpx`
+- **Auth layer:** handwritten (token lifecycle is too sensitive to template — see the
+  [design doc](../../docs/productization-evolution/in-progress/client-sdk-facility-design.md))
+
+```bash
+pip install fulla-oauth2
+```
+
+> Published to PyPI since v1.3.0 (release pipeline's `sdk-python` job). Prefer the released wheel; a
+> checkout install (`pip install clients/python`) still works for development.
+
+## Quickstart: machine-to-machine (client_credentials)
+
+```python
+from fulla import m2m_client
+from fulla.generated.api.o_auth_2 import post_oauth2_introspect
+from fulla.generated.models.post_oauth_2_introspect_body import PostOauth2IntrospectBody
+
+client = m2m_client(
+    "http://localhost:5555",
+    client_id="backend-svc",
+    client_secret="…",
+    scopes=["tokens:read"],
+)
+
+# Every request carries a valid Bearer token: fetched lazily, cached,
+# refreshed 30 s before expiry, force-refreshed once on a 401.
+result = post_oauth2_introspect.sync(
+    client=client, body=PostOauth2IntrospectBody(token=some_access_token)
+)
+print(result.active)
+
+# When done: closes BOTH the API client and the auth layer's token pool
+# (closing the generated client alone leaks the token connection pool).
+from fulla import close_m2m_client
+close_m2m_client(client)
+```
+
+Async is symmetric:
+
+```python
+from fulla import async_m2m_client
+
+client = async_m2m_client("http://localhost:5555", "backend-svc", "…", scopes=["tokens:read"])
+result = await post_oauth2_introspect.asyncio(client=client, body=body)
+```
+
+One-shot token fetch (scripts, benchmarks):
+
+```python
+from fulla import fetch_client_credentials_token
+
+token, expires_in = fetch_client_credentials_token(
+    "http://localhost:5555", "backend-svc", "…", ["tokens:read"]
+)
+```
+
+## Introspect / revoke (client Basic authentication)
+
+`/oauth2/introspect` and `/oauth2/revoke` authenticate the *calling client*, not a user bearer
+token (RFC 7662 §2.1). Use a client whose every request carries HTTP Basic — confidential
+clients must use Basic; the server rejects credentials in the body (F-017):
+
+```python
+from fulla import basic_auth_client
+
+client = basic_auth_client("http://localhost:5555", "backend-svc", "…")
+result = post_oauth2_introspect.sync(client=client, body=PostOauth2IntrospectBody(token=tok))
+```
+
+## Authorization-code flow (web apps, with PKCE)
+
+```python
+from fulla import AuthorizationCodeFlow, PkcePair
+
+flow = AuthorizationCodeFlow(
+    "http://localhost:5555", "my-client", "my-secret",
+    redirect_uri="https://my.app/callback", scopes=["openid", "profile"],
+)
+pkce = PkcePair.generate()
+authorize_url = flow.build_authorize_url(state=session_csrf, pkce=pkce)
+# → send the user's browser to authorize_url; Fulla redirects back with ?code=…&state=…
+# → VERIFY state, then:
+tokens = flow.exchange_code(code, pkce.verifier)
+# … later; Fulla rotates refresh tokens on every use (V008):
+tokens = flow.refresh(tokens.refresh_token)
+```
+
+## Generated API modules
+
+Everything under `fulla.generated` is the typed surface of the whole server API:
+
+```python
+from fulla.generated.api.open_id_connect import get_well_known_openid_configuration
+from fulla.generated.api.o_auth_2 import get_oauth2_userinfo, post_oauth2_token
+from fulla.generated.models.token_request import TokenRequest
+```
+
+Each endpoint module offers `sync`, `sync_detailed`, `asyncio`, `asyncio_detailed`. The
+`*_detailed` variants return status code + raw response alongside the parsed model.
+
+## Development
+
+```bash
+cd clients/python
+pip install -e ".[dev]"
+pytest                       # unit tests (in-process MockTransport, no server needed)
+
+# integration tests (needs a running full stack, see tests/integration/)
+FULLA_BASE_URL=http://127.0.0.1:5555 pytest tests/integration
+```
+
+Regenerating the committed `src/fulla/generated/` tree after an `openapi.yaml` change:
+
+```bash
+pip install openapi-python-client==0.29.0
+python tools/clients/regen_clients.py            # from the repo root
+```
+
+CI (`.github/workflows/clients-sdk.yml`) re-generates and diffs on every PR touching
+`clients/**` or the spec — committed generated code can never go stale.
+
+## Versioning
+
+The package version is locked to the server's `cmake/Version.cmake` (enforced by
+`tools/clients/regen_clients.py --version-only` at release time). Breaking HTTP API changes
+require a major bump on both sides (guarded by the `openapi-governance` oasdiff workflow).
+
+## Local network note
+
+If `go`/module proxies are unreachable from your network, the Go generator download mentioned
+in the regen docs needs a GOPROXY mirror (e.g. `GOPROXY=https://goproxy.cn,direct`). This only
+affects regenerating `clients/go` — installing and using this Python package is unaffected.

fulla_oauth2-1.0.0/examples/client_credentials_demo.py

@@ -0,0 +1,53 @@
+"""End-to-end demo: client_credentials against a running Fulla server.
+
+Usage:
+    python examples/client_credentials_demo.py [base_url] [client_id] [client_secret]
+
+Defaults match the development seed (apps/server/seed/dev_backend_client.sql):
+backend-svc / test-secret on http://127.0.0.1:5555. Start the full stack first
+(see the repo README); this script is the Python analogue of benchmark
+scenario S2 (client_credentials token flow) plus introspection.
+
+Exit code 0 = all steps passed; non-zero = the first failure.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from fulla import basic_auth_client, fetch_client_credentials_token  # noqa: E402
+from fulla.generated.api.o_auth_2 import post_oauth2_introspect  # noqa: E402
+from fulla.generated.models.post_oauth_2_introspect_body import (  # noqa: E402
+    PostOauth2IntrospectBody,
+)
+
+
+def main() -> int:
+    base_url = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("FULLA_BASE_URL", "http://127.0.0.1:5555")
+    client_id = sys.argv[2] if len(sys.argv) > 2 else os.environ.get("FULLA_CLIENT_ID", "backend-svc")
+    client_secret = sys.argv[3] if len(sys.argv) > 3 else os.environ.get("FULLA_CLIENT_SECRET", "test-secret")
+
+    print(f"[demo] fetching client_credentials token from {base_url} as {client_id}")
+    access_token, expires_in = fetch_client_credentials_token(
+        base_url, client_id, client_secret, ["tokens:read"]
+    )
+    print(f"[demo] got access_token ({len(access_token)} chars), expires_in={expires_in}s")
+
+    client = basic_auth_client(base_url, client_id, client_secret)
+    result = post_oauth2_introspect.sync(
+        client=client, body=PostOauth2IntrospectBody(token=access_token)
+    )
+    if not result.active:
+        print("[demo] FAIL: freshly obtained token introspects as inactive")
+        return 1
+    print(f"[demo] introspect: active=True client_id={result.client_id} scope={result.scope}")
+    print("[demo] OK")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fulla_oauth2-1.0.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fulla-oauth2"
+version = "1.0.0"
+description = "Python client SDK for Fulla, the embeddable C++ OAuth2/OIDC authorization server"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Fulla contributors" }]
+keywords = ["oauth2", "oidc", "openid-connect", "fulla", "authorization", "client", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+# Dependency floors/ceilings mirror what openapi-python-client 0.29.0 emits
+# for the generated subpackage; generator upgrades go through a dedicated PR.
+dependencies = [
+    "httpx>=0.23.1,<0.29.0",
+    "attrs>=22.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/voidvec/fulla"
+Documentation = "https://github.com/voidvec/fulla/tree/master/clients/python"
+Repository = "https://github.com/voidvec/fulla"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.25",
+    "build>=1.2",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fulla"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "examples", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

fulla_oauth2-1.0.0/src/fulla/__init__.py

@@ -0,0 +1,52 @@
+"""Fulla Python client SDK.
+
+Distribution name ``fulla-oauth2`` (the shorter ``fulla`` name on
+PyPI belongs to an unrelated project); import name ``fulla``.
+
+Public API:
+
+- :func:`m2m_client` / :func:`async_m2m_client` -- ready-to-use generated
+  clients with automatic client_credentials token management.
+- :func:`basic_auth_client` -- HTTP-Basic client for introspect/revoke.
+- :func:`fetch_client_credentials_token` -- one-shot token fetch.
+- :class:`AuthorizationCodeFlow` / :class:`PkcePair` -- authorization-code
+  grant helpers (URL building, PKCE S256, code exchange, refresh).
+- :mod:`fulla.generated` -- the full typed API surface generated from
+  apps/server/openapi.yaml (see its own README for endpoint modules).
+"""
+
+from .m2m import (
+    AsyncClientCredentialsAuth,
+    FullaAuthError,
+    ClientCredentialsAuth,
+    async_m2m_client,
+    basic_auth_client,
+    close_async_m2m_client,
+    close_m2m_client,
+    fetch_client_credentials_token,
+    m2m_client,
+)
+from .oauth import AuthorizationCodeFlow, PkcePair, create_pkce_challenge
+
+try:  # pragma: no cover - packaging-time fallback only
+    from importlib.metadata import PackageNotFoundError, version
+
+    __version__ = version("fulla-oauth2")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "__version__",
+    "AsyncClientCredentialsAuth",
+    "FullaAuthError",
+    "AuthorizationCodeFlow",
+    "ClientCredentialsAuth",
+    "PkcePair",
+    "async_m2m_client",
+    "basic_auth_client",
+    "close_async_m2m_client",
+    "close_m2m_client",
+    "create_pkce_challenge",
+    "fetch_client_credentials_token",
+    "m2m_client",
+]

fulla_oauth2-1.0.0/src/fulla/generated/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing OAuth2 Authorization Server API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

fulla_oauth2-1.0.0/src/fulla/generated/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

fulla_oauth2-1.0.0/src/fulla/generated/api/admin/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""