Release 0.1.0

README.md

@@ -7,13 +7,13 @@
 - Contact us: support@dataone.org
 - [DataONE discussions](https://github.com/DataONEorg/dataone/discussions)
 
-*Product overview goes here.* Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+The `dataone-auth` module provides a framework-agnostic OpenID Connect (OIDC) authentication adapter for Python applications. Using `joserfc` and `Authlib`, its core purpose is to handle JSON Web Token (JWT) validation so that DataONE Python applications can seamlessly integrate OIDC authentication, regardless of what framework that application uses. Currently, `dataone-auth` supports both Flask and FastAPI. To integrate `dataone-auth` into an existing app, the application only needs to create an auth client (`create_client`), use the `login`, `authorize`, `refresh` methods on the corresponding endpoints, and utilize the `require_scope` helper either as a decorator or `Depends` function to protect secure endpoints. For more detail on usage, see the examples below. 
 
 DataONE creates open source, community projects.  We [welcome contributions](./CONTRIBUTING.md) in many forms, including code, graphics, documentation, bug reports, testing, etc.  Use the [DataONE discussions](https://github.com/DataONEorg/dataone/discussions) to discuss these contributions with us.
 
 ## Documentation
 
-Documentation is a work in progress, and can be found ...
+Documentation is a work in progress, and can be found in [docs](./docs).
 
 ## Development build
 
@@ -37,15 +37,115 @@ To run the code formatter and linter, use Ruff:
 
 - `uv run ruff check .`
 
-## Usage Example
+## Usage Examples
 
-To view more details about the Public API - see interface documentation
+### Flask
+
+Below is a minimal example for a Flask application. For the Flask implementation, applying `ProxyFix` is recommended to ensure correct redirect URIs when the app is running behind a reverse proxy or load balancer. Following standard Flask extension patterns, the `auth_client` must be explicitly bound to the application using `init_app()`. Once initialized, protect any endpoint by stacking the `@auth_client.require_scope(...)` decorator below the route definition. This automatically intercepts the Bearer token, validates the OIDC claims against the provider's JWKS, and injects the resulting claims dictionary into the view function. Note that routes can also use `@auth_client.require_token(...)` if checking scopes is not necessary. Optionally, HTTP methods can be passed to either decorator to specify auth requirements based on method if necessary.
 
 ```python
-import dataone.auth
+import json
+import os
+from flask import Flask, jsonify, request, url_for
+from werkzeug.middleware.proxy_fix import ProxyFix
+from dataone.auth import AuthFactory, load_client_secrets
+
+# --- Constants & Logging ---
+ACCESS_MODE_AUTHENTICATED = "authenticated"
+scopes = ["ogdc:admin"]
+
+# --- App Initialization ---
+app = Flask(__name__)
+app.config.update({"SECRET_KEY": os.getenv("FLASK_SECRET_KEY", os.urandom(32).hex())})
+
+if not isinstance(app.wsgi_app, ProxyFix):
+    app.wsgi_app = ProxyFix(app.wsgi_app, x_proto=1, x_host=1)
+
+# --- Auth Setup ---
+secrets = load_client_secrets()
+auth_client = AuthFactory.create_client("flask", secrets, scopes)
+auth_client.init_app(app)
+app.extensions['dataone_auth'] = auth_client
+
+# --- Routes ---
+@app.route("/login")
+def login():
+    return auth_client.login(redirect_uri=url_for("authorize", _external=True))
+
+@app.route("/authorize")
+def authorize():
+    return auth_client.authorize()
+
+@app.route("/refresh", methods=["POST"])
+def refresh_token():
+    return auth_client.refresh(request_json=request.get_json(silent=True))
+
+@app.route("/profile", methods=["GET"])
+@auth_client.require_scope("ogdc:admin")
+def profile(claims):
+    """Protected resource endpoint requiring 'ogdc:admin' scope."""
+    return jsonify({
+        "message": f"Authorization succeeded, {claims.get('name', 'User')}",
+        "claims": claims  # The claims object is already a dictionary!
+    }), 200
+
+# --- Execution ---
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=int("4000"), debug=True)
+```
 
-# Example code here...
+### FastAPI
 
+Below is a minimal example for a FastAPI application. Unlike Flask, FastAPI doesn't require an `init_app` step; the `auth_client` is ready to use immediately upon creation. Note that `SessionMiddleware` must be added to the app to handle the OIDC state and nonce during the browser-based login and authorization flow. For the API endpoints, the heavy lifting happens within the `Depends(auth_client.require_scope(...))` dependency, which automatically intercepts the Bearer token, validates the OIDC claims against the provider's JWKS, and injects the ready-to-use claims dictionary  into the route handler. Note that routes can also use `Depends(auth_client.require_token(...))` if checking scopes is not necessary. Optionally, HTTP methods can be passed to either `Depends` to specify auth requirements based on method if necessary.
+
+```python
+import os
+from fastapi import Depends, FastAPI, Request
+from fastapi.security import HTTPBearer
+from starlette.middleware.sessions import SessionMiddleware
+from dataone.auth import AuthFactory, load_client_secrets
+
+# --- Constants & Logging ---
+ACCESS_MODE_AUTHENTICATED = "authenticated"
+scopes = ["ogdc:admin"]
+
+# --- App Initialization ---
+app = FastAPI(title="DataONE OIDC API")
+app.add_middleware(
+    SessionMiddleware, 
+    secret_key=os.getenv("SECRET_KEY", os.urandom(32).hex())
+)
+
+# --- Auth Setup ---
+secrets = load_client_secrets()
+auth_client = AuthFactory.create_client("fastapi", secrets, scopes)
+
+security = HTTPBearer()
+# --- Routes ---
+@app.get("/login")
+async def login(request: Request):
+    return await auth_client.login(request, redirect_uri=str(request.url_for("authorize")))
+
+@app.get("/authorize")
+async def authorize(request: Request):
+    return await auth_client.authorize(request)
+
+@app.post("/refresh")
+async def refresh(request: Request):
+    return await auth_client.refresh(await request.json())
+
+@app.get("/profile")
+async def profile(claims: dict = Depends(auth_client.require_scope("ogdc:admin"))):
+    """Protected resource endpoint."""
+    return {
+        "message": f"Authorization succeeded, {claims.get('name', 'User')}",
+        "claims": claims
+    }
+
+# --- Execution ---
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=4000, proxy_headers=True, forwarded_allow_ips="*")
 ```
 
 ## License

docs/README.md

@@ -0,0 +1,3 @@
+# Docs
+
+- [Auth Sequence Diagram](./diagrams/auth-sequence.md)

docs/diagrams/auth-sequence.md

@@ -0,0 +1,45 @@
+### DataONE Auth
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant User as User (Browser)
+    participant API as DataONE Auth Client
+    participant KC as Keycloak Server
+
+    Note over User, KC: [1] The Login Initiation
+    User->>API: GET /login
+    API-->>User: 302 Redirect to Keycloak (with client_id & redirect_uri)
+
+    User->>KC: Access Keycloak Login Page
+    User->>KC: Submit Credentials
+    KC->>KC: Authenticate User
+    KC-->>User: 302 Redirect to VB API /authorize?code=XYZ
+
+    Note over API, KC: [2] The Backchannel Exchange
+    User->>API: GET /authorize?code=XYZ
+    activate API
+    API->>KC: POST /token (code=XYZ, client_id, client_secret)
+    KC->>KC: Validate Code & Secret
+    KC-->>API: Returns: Access Token + Refresh Token
+    API-->>User: Returns Tokens
+    deactivate API
+
+    Note over User, API: [3] Standard Operation
+    User->>API: GET /data (Header: Authorization: Bearer <AT>)
+    API->>API: Local Validation of AT
+    API-->>User: 200 OK (Data)
+
+    Note over User, KC: [4] The Refresh Flow
+    User->>API: POST /refresh (Body: refresh_token)
+    activate API
+    API->>KC: POST /token (grant_type=refresh_token, client_secret)
+    alt RT is Valid
+        KC-->>API: New Access Token + New Refresh Token
+        API-->>User: 200 OK (New Tokens)
+    else RT is Invalid/Expired
+        KC-->>API: 400 Bad Request (Invalid Grant)
+        API-->>User: 302 Redirect to /login
+    end
+    deactivate API
+```

noxfile.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import nox
+
+DIR = Path(__file__).parent.resolve()
+
+nox.needs_version = ">=2024.3.2"
+# Typing `nox` with no arguments will automatically run these two sessions
+nox.options.sessions = ["typecheck", "tests"]
+nox.options.default_venv_backend = "uv|virtualenv"
+
+if os.environ.get("ENVIRONMENT") == "dev":
+    # Use existing venvs where possible in dev
+    nox.options.reuse_existing_virtualenvs = True
+else:
+    # All other envs should have the nox venvs recreated.
+    nox.options.reuse_existing_virtualenvs = False
+
+nox.options.stop_on_first_error = True
+
+
+@nox.session(python="3.11")
+def typecheck(session: nox.Session) -> None:
+    """Run typechecker (mypy)."""
+    session.install("mypy", ".[flask,fastapi,starlette]")
+    run_args = session.posargs if session.posargs else ["src"]
+    session.run("mypy", *run_args)
+
+
+@nox.session(python="3.11")
+def tests(session: nox.Session) -> None:
+    """Run all tests."""
+    session.install("pytest", ".")
+    run_args = session.posargs if session.posargs else ["tests"]
+    session.run("pytest", *run_args)

pyproject.toml

@@ -4,13 +4,31 @@ version = "0.1.0"
 description = "DataONE OIDC Auth package"
 readme = "README.md"
 authors = [
+    { name = "Rushiraj Nenuji", email = "nenuji@nceas.ucsb.edu" },
+    { name = "Jeanette Clark", email = "jclark@nceas.ucsb.edu" },
     { name = "Matthew B. Jones", email = "jones@nceas.ucsb.edu" }
 ]
-requires-python = ">=3.13"
-dependencies = []
+requires-python = ">=3.11"
+dependencies = [
+    "authlib>=1.7.2",
+    "httpx>=0.28.1",
+    "joserfc>=1.6.5",
+    "requests>=2.33.1",
+]
 
-[project.scripts]
-dataone = "dataone:main"
+[project.optional-dependencies]
+flask = [
+    "flask>=3.1.3",
+    "werkzeug>=3.1.8",
+]
+fastapi = [
+    "fastapi>=0.136.1",
+    "httpx>=0.28.1",
+    "starlette>=1.0.0",
+]
+starlette = [
+    "httpx>=0.28.1",
+]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/dataone"]
@@ -23,6 +41,8 @@ build-backend = "hatchling.build"
 dev = [
     "pytest>=9.0.3",
     "ruff>=0.15.12",
+    "nox",
+    "mypy",
 ]
 
 [tool.ruff]
@@ -41,3 +61,9 @@ python_files = ["test_*.py", "*_test.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
 addopts = "-v"
+
+[[tool.mypy.overrides]]
+module = [
+    "authlib.*",
+]
+ignore_missing_imports = true