google-adk-extras 0.2.7__tar.gz → 0.3.1__tar.gz

{google_adk_extras-0.2.7/src/google_adk_extras.egg-info → google_adk_extras-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-adk-extras
-Version: 0.2.7
+Version: 0.3.1
 Summary: Production-ready services and FastAPI wiring for Google ADK
 Home-page: https://github.com/DeadMeme5441/google-adk-extras
 Author: DeadMeme5441
@@ -94,7 +94,7 @@ If you plan to use specific backends, also install their clients (examples):
 - Redis: `uv pip install redis`
 - S3: `uv pip install boto3`
   
-Note on credentials (0.2.7): This release removes custom credential services and URI helpers from this package. For outbound credentials used by tools, rely on ADK’s experimental BaseCredentialService (e.g., InMemory/SessionState) or your own ADK-compatible implementation. Inbound API authentication (protecting /run and streaming routes) will be provided as an optional FastAPI layer separately.
+Note on credentials (0.3.0): Outbound credentials for tools remain ADK’s concern (use ADK’s BaseCredentialService). Inbound API authentication is now available as an optional FastAPI layer in this package (see Auth below). You can run fully open (no auth) or enable API Key, Basic, or JWT (including first‑party issuance backed by SQL).
 
 
 ## Quickstart (FastAPI)
@@ -104,6 +104,7 @@ Use the fluent builder to wire services. Then run with uvicorn.
 ```python
 # app.py
 from google_adk_extras import AdkBuilder
+from google_adk_extras.auth import AuthConfig, JwtIssuerConfig, JwtValidatorConfig
 
 app = (
     AdkBuilder()
@@ -127,6 +128,77 @@ uvicorn app:app --reload
 If you don’t keep agents on disk, register them programmatically and use a custom loader (see below).
 
 
+## Auth (optional)
+
+Auth is entirely optional. By default, all endpoints are open (no auth). To enable protection, pass `auth_config` into `get_enhanced_fast_api_app` via the builder or directly.
+
+Supported inbound methods:
+- API Key: `X-API-Key: <key>` header (or `?api_key=` query). Keys can be static via config, or issued/rotated via SQL‑backed endpoints.
+- HTTP Basic: `Authorization: Basic base64(user:pass)` for quick human/internal testing. Can validate against in‑memory map or the SQL users table.
+- Bearer JWT (validate): Accept JWTs from Google/Auth0/Okta/etc. via JWKS, or HS256 secret in dev. Enforces iss/aud/exp/nbf.
+- Bearer JWT (issue): First‑party issuer with HS256, tokens minted from `/auth/token`, users stored in SQL (SQLite/Postgres/MySQL).
+
+Minimal enablement (JWT validate only):
+
+```python
+from google_adk_extras.auth import AuthConfig, JwtValidatorConfig
+
+auth = AuthConfig(
+    enabled=True,
+    jwt_validator=JwtValidatorConfig(
+        jwks_url="https://accounts.google.com/.well-known/openid-configuration",  # example
+        issuer="https://accounts.google.com",
+        audience="your-api-audience",
+    ),
+)
+
+app = (
+    AdkBuilder()
+      .with_agents_dir("./agents")
+      .build_fastapi_app()
+)
+```
+
+First‑party issuer + validate (single shared HS256 secret) with SQL connector:
+
+```python
+from google_adk_extras.auth import AuthConfig, JwtIssuerConfig, JwtValidatorConfig
+
+issuer = JwtIssuerConfig(
+    enabled=True,
+    issuer="https://local-issuer",
+    audience="adk-api",
+    algorithm="HS256",
+    hs256_secret="topsecret",
+    database_url="sqlite:///./auth.db",  # also supports Postgres/MySQL
+)
+validator = JwtValidatorConfig(
+    issuer=issuer.issuer,
+    audience=issuer.audience,
+    hs256_secret=issuer.hs256_secret,
+)
+
+auth = AuthConfig(enabled=True, jwt_issuer=issuer, jwt_validator=validator)
+
+app = (
+    AdkBuilder()
+      .with_agents_dir("./agents")
+      .build_fastapi_app()
+)
+```
+
+Issuing and using tokens/keys at runtime:
+- Register user: `POST /auth/register?username=alice&password=wonder`
+- Token (password): `POST /auth/token?grant_type=password&username=alice&password=wonder`
+- Refresh: `POST /auth/refresh?user_id=<uid>&refresh_token=<jti>`
+- Create API key: `POST /auth/api-keys` (auth required) → returns `{ id, api_key }` (plaintext shown once)
+- List keys: `GET /auth/api-keys` (auth required)
+- Revoke key: `DELETE /auth/api-keys/{id}` (auth required)
+- Use API key: add `X-API-Key: <api_key>` to any protected route (keys currently allow full access)
+
+Protected routes include `/run`, `/run_sse`, all `/apps/...` session/artifact/eval endpoints, `/debug/*`, `/builder/*`, and optionally `/list-apps` and `/apps/{app}/metrics-info`.
+
+
 ## Quickstart (Runner)
 
 Create a Runner wired with your chosen backends. Use agent name (filesystem loader) or pass an agent instance.

{google_adk_extras-0.2.7 → google_adk_extras-0.3.1}/README.md

@@ -51,7 +51,7 @@ If you plan to use specific backends, also install their clients (examples):
 - Redis: `uv pip install redis`
 - S3: `uv pip install boto3`
   
-Note on credentials (0.2.7): This release removes custom credential services and URI helpers from this package. For outbound credentials used by tools, rely on ADK’s experimental BaseCredentialService (e.g., InMemory/SessionState) or your own ADK-compatible implementation. Inbound API authentication (protecting /run and streaming routes) will be provided as an optional FastAPI layer separately.
+Note on credentials (0.3.0): Outbound credentials for tools remain ADK’s concern (use ADK’s BaseCredentialService). Inbound API authentication is now available as an optional FastAPI layer in this package (see Auth below). You can run fully open (no auth) or enable API Key, Basic, or JWT (including first‑party issuance backed by SQL).
 
 
 ## Quickstart (FastAPI)
@@ -61,6 +61,7 @@ Use the fluent builder to wire services. Then run with uvicorn.
 ```python
 # app.py
 from google_adk_extras import AdkBuilder
+from google_adk_extras.auth import AuthConfig, JwtIssuerConfig, JwtValidatorConfig
 
 app = (
     AdkBuilder()
@@ -84,6 +85,77 @@ uvicorn app:app --reload
 If you don’t keep agents on disk, register them programmatically and use a custom loader (see below).
 
 
+## Auth (optional)
+
+Auth is entirely optional. By default, all endpoints are open (no auth). To enable protection, pass `auth_config` into `get_enhanced_fast_api_app` via the builder or directly.
+
+Supported inbound methods:
+- API Key: `X-API-Key: <key>` header (or `?api_key=` query). Keys can be static via config, or issued/rotated via SQL‑backed endpoints.
+- HTTP Basic: `Authorization: Basic base64(user:pass)` for quick human/internal testing. Can validate against in‑memory map or the SQL users table.
+- Bearer JWT (validate): Accept JWTs from Google/Auth0/Okta/etc. via JWKS, or HS256 secret in dev. Enforces iss/aud/exp/nbf.
+- Bearer JWT (issue): First‑party issuer with HS256, tokens minted from `/auth/token`, users stored in SQL (SQLite/Postgres/MySQL).
+
+Minimal enablement (JWT validate only):
+
+```python
+from google_adk_extras.auth import AuthConfig, JwtValidatorConfig
+
+auth = AuthConfig(
+    enabled=True,
+    jwt_validator=JwtValidatorConfig(
+        jwks_url="https://accounts.google.com/.well-known/openid-configuration",  # example
+        issuer="https://accounts.google.com",
+        audience="your-api-audience",
+    ),
+)
+
+app = (
+    AdkBuilder()
+      .with_agents_dir("./agents")
+      .build_fastapi_app()
+)
+```
+
+First‑party issuer + validate (single shared HS256 secret) with SQL connector:
+
+```python
+from google_adk_extras.auth import AuthConfig, JwtIssuerConfig, JwtValidatorConfig
+
+issuer = JwtIssuerConfig(
+    enabled=True,
+    issuer="https://local-issuer",
+    audience="adk-api",
+    algorithm="HS256",
+    hs256_secret="topsecret",
+    database_url="sqlite:///./auth.db",  # also supports Postgres/MySQL
+)
+validator = JwtValidatorConfig(
+    issuer=issuer.issuer,
+    audience=issuer.audience,
+    hs256_secret=issuer.hs256_secret,
+)
+
+auth = AuthConfig(enabled=True, jwt_issuer=issuer, jwt_validator=validator)
+
+app = (
+    AdkBuilder()
+      .with_agents_dir("./agents")
+      .build_fastapi_app()
+)
+```
+
+Issuing and using tokens/keys at runtime:
+- Register user: `POST /auth/register?username=alice&password=wonder`
+- Token (password): `POST /auth/token?grant_type=password&username=alice&password=wonder`
+- Refresh: `POST /auth/refresh?user_id=<uid>&refresh_token=<jti>`
+- Create API key: `POST /auth/api-keys` (auth required) → returns `{ id, api_key }` (plaintext shown once)
+- List keys: `GET /auth/api-keys` (auth required)
+- Revoke key: `DELETE /auth/api-keys/{id}` (auth required)
+- Use API key: add `X-API-Key: <api_key>` to any protected route (keys currently allow full access)
+
+Protected routes include `/run`, `/run_sse`, all `/apps/...` session/artifact/eval endpoints, `/debug/*`, `/builder/*`, and optionally `/list-apps` and `/apps/{app}/metrics-info`.
+
+
 ## Quickstart (Runner)
 
 Create a Runner wired with your chosen backends. Use agent name (filesystem loader) or pass an agent instance.

google_adk_extras-0.3.1/docs/auth.md

@@ -0,0 +1,79 @@
+# Auth (Optional)
+
+Inbound API authentication is optional. If you don’t pass an `auth_config`, all routes are open (useful for local dev). When enabled, the middleware protects sensitive routes and enforces identity where appropriate.
+
+Supported methods:
+- API Key
+  - Send `X-API-Key: <token>` header or `?api_key=<token>` query.
+  - Keys can be static via config or issued/rotated via SQL‑backed endpoints.
+- HTTP Basic
+  - `Authorization: Basic base64(user:pass)`.
+  - Checks an in‑memory map or the SQL users table when configured.
+- Bearer JWT (validate)
+  - Validate JWTs from OIDC providers (Google, Auth0, Okta, etc.) via JWKS.
+  - Or use HS256 with a shared secret in dev.
+- Bearer JWT (issue)
+  - First‑party issuer backed by SQL; exposes `/auth/register`, `/auth/token`, `/auth/refresh`.
+
+## Quick examples
+
+### Enable JWT validate only
+```python
+from google_adk_extras import AdkBuilder
+from google_adk_extras.auth import AuthConfig, JwtValidatorConfig
+
+auth = AuthConfig(
+    enabled=True,
+    jwt_validator=JwtValidatorConfig(
+        jwks_url="https://YOUR_ISSUER/.well-known/jwks.json",
+        issuer="https://YOUR_ISSUER",
+        audience="your-api-audience",
+    ),
+)
+
+app = AdkBuilder().with_agents_dir("./agents").build_fastapi_app()
+```
+
+### First‑party issuer + validate (HS256) and SQL store
+```python
+from google_adk_extras import AdkBuilder
+from google_adk_extras.auth import AuthConfig, JwtIssuerConfig, JwtValidatorConfig
+
+issuer = JwtIssuerConfig(
+    enabled=True,
+    issuer="https://local-issuer",
+    audience="adk-api",
+    algorithm="HS256",
+    hs256_secret="topsecret",
+    database_url="sqlite:///./auth.db",
+)
+validator = JwtValidatorConfig(issuer=issuer.issuer, audience=issuer.audience, hs256_secret=issuer.hs256_secret)
+
+auth = AuthConfig(enabled=True, jwt_issuer=issuer, jwt_validator=validator)
+
+app = AdkBuilder().with_agents_dir("./agents").build_fastapi_app()
+```
+
+### API key management endpoints (SQL store)
+- `POST /auth/api-keys` → `{ id, api_key }` (plaintext shown once)
+- `GET /auth/api-keys` → list metadata
+- `DELETE /auth/api-keys/{id}` → revoke
+
+Use `X-API-Key: <api_key>` (or `?api_key=`) to access protected routes.
+
+## What’s protected
+- Always: `POST /run`, `POST /run_sse`, `GET/POST/DELETE /apps/...`, `/debug/*`, `/builder/*`.
+- Optional: `/list-apps` and `/apps/{app}/metrics-info` (toggled in `AuthConfig`).
+- Ownership: when the URL contains `/users/{user_id}/...`, the `sub` from the token must match `user_id` (API key bypass permitted).
+
+## Optional by design
+- No‑auth is the default. Enable auth only when you’re ready.
+- You can mix modes: e.g., JWT for users and API keys for automation.
+
+```python
+# Direct call if not using the builder
+from google_adk_extras.enhanced_fastapi import get_enhanced_fast_api_app
+from google_adk_extras.auth import AuthConfig
+app = get_enhanced_fast_api_app(..., auth_config=AuthConfig(enabled=True, api_keys=["test"]))
+```
+

{google_adk_extras-0.2.7 → google_adk_extras-0.3.1}/docs/index.md

@@ -14,6 +14,11 @@ What this is not: a fork of ADK. It builds on top of google-adk.
 - `EnhancedAdkWebServer`
 - `EnhancedRunner` (thin wrapper)
 - `CustomAgentLoader` (programmatic agents)
-- Services via subpackages: `sessions`, `artifacts`, `memory`, `credentials`
+- Services via subpackages: `sessions`, `artifacts`, `memory` (optional inbound auth lives under `auth/`)
 
 See Quickstarts for copy‑paste examples.
+
+Additional guides:
+- [FastAPI Integration](fastapi.md)
+- [Streaming](streaming.md)
+- [Auth (Optional)](auth.md)

google_adk_extras-0.3.1/examples/adk_server_8015.py

@@ -0,0 +1,43 @@
+"""Spin up an ADK FastAPI server on 127.0.0.1:8015 with in-memory services.
+
+This script uses google_adk_extras.get_enhanced_fast_api_app with a simple
+programmatic agent loader. It is intended only to inspect the OpenAPI schema
+and enumerate endpoints exposed by the ADK web server.
+"""
+
+from typing import AsyncGenerator, Optional
+
+from fastapi import FastAPI
+
+from google.genai import types
+from google.adk.events.event import Event
+from google.adk.agents.base_agent import BaseAgent
+
+from google_adk_extras.custom_agent_loader import CustomAgentLoader
+from google_adk_extras.enhanced_fastapi import get_enhanced_fast_api_app
+
+
+class _DummyAgent(BaseAgent):
+    """Minimal agent; not used for OpenAPI generation, but loadable if needed."""
+
+    def __init__(self, name: str = "dummy"):
+        super().__init__(name)
+
+    async def run_async(self, ctx) -> AsyncGenerator[Event, None]:
+        # Emit a trivial final event; unlikely to be executed in this script.
+        content = types.Content(parts=[types.Part(text="ok")])
+        yield Event(author=self.name, content=content)
+
+
+def build_app() -> FastAPI:
+    loader = CustomAgentLoader()
+    app = get_enhanced_fast_api_app(
+        agent_loader=loader,
+        web=False,                 # no static UI
+        enable_streaming=False,    # focus on ADK core endpoints
+        allow_origins=["*"]
+    )
+    return app
+
+
+app = build_app()

{google_adk_extras-0.2.7 → google_adk_extras-0.3.1}/mkdocs.yml

@@ -14,6 +14,7 @@ nav:
   - Getting Started: getting-started.md
   - Quickstarts: quickstarts.md
   - FastAPI Integration: fastapi.md
+  - Auth (Optional): auth.md
   - Streaming: streaming.md
   - Services:
       - Durable Services: services.md
@@ -46,10 +47,10 @@ plugins:
         - quickstarts.md: A few end-to-end snippets to copy/paste
         FastAPI & A2A:
         - fastapi.md: Build a FastAPI app with AdkBuilder and enable A2A
+        Auth:
+        - auth.md: Optional inbound API authentication
         Durable Services:
         - services.md: Sessions, artifacts, memory backends and trade-offs
-        Credentials:
-        # credentials docs removed; use ADK documentation for outbound creds
         Programmatic Agents:
         - agent-loading.md: Custom loaders and in-memory registrations
         Configuration:

{google_adk_extras-0.2.7 → google_adk_extras-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "google-adk-extras"
-version = "0.2.7"
+version = "0.3.1"
 description = "Production-ready services and FastAPI wiring for Google ADK"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"

{google_adk_extras-0.2.7 → google_adk_extras-0.3.1}/src/google_adk_extras/__init__.py

@@ -28,4 +28,4 @@ __all__ = [
     "CustomAgentLoader",
 ]
 
-__version__ = "0.2.7"
+__version__ = "0.3.1"

{google_adk_extras-0.2.7 → google_adk_extras-0.3.1}/src/google_adk_extras/adk_builder.py

@@ -683,6 +683,7 @@ class AdkBuilder:
             eval_storage_uri=self._eval_storage_uri,
             allow_origins=self._allow_origins,
             web=self._web_ui,
+            # Expose future override via builder when needed
             a2a=self._a2a,
             programmatic_a2a=self._a2a_expose_programmatic,
             programmatic_a2a_mount_base=self._a2a_programmatic_mount_base,

google_adk_extras-0.3.1/src/google_adk_extras/auth/__init__.py

@@ -0,0 +1,10 @@
+from .config import AuthConfig, JwtIssuerConfig, JwtValidatorConfig
+from .attach import attach_auth
+
+__all__ = [
+    "AuthConfig",
+    "JwtIssuerConfig",
+    "JwtValidatorConfig",
+    "attach_auth",
+]
+

google_adk_extras-0.3.1/src/google_adk_extras/auth/attach.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, Depends, FastAPI, HTTPException, Request
+import base64
+from fastapi.security import APIKeyHeader
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from .config import AuthConfig, JwtIssuerConfig, JwtValidatorConfig
+from .jwt_utils import decode_jwt, encode_jwt, now_ts
+from typing import Any
+
+
+def attach_auth(app: FastAPI, cfg: Optional[AuthConfig]) -> None:
+    """Attach optional auth to the provided FastAPI app.
+
+    - Adds middleware that enforces auth on sensitive routes.
+    - Optionally registers token issuance endpoints if configured.
+    """
+    if not cfg or not cfg.enabled or cfg.allow_no_auth:
+        return
+
+    validator = cfg.jwt_validator
+    issuer_cfg = cfg.jwt_issuer
+    api_keys = set(cfg.api_keys or [])
+    basic_users = cfg.basic_users or {}
+    auth_store: Optional[Any] = None
+    if issuer_cfg and issuer_cfg.database_url:
+        try:
+            from .sql_store import AuthStore  # type: ignore
+            auth_store = AuthStore(issuer_cfg.database_url)
+        except Exception:
+            # SQL store not available; API key issuance and password grants will be unavailable.
+            auth_store = None
+
+    # Security helpers
+    api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+    async def _authenticate(request: Request) -> dict:
+        # API Key
+        api_key = request.query_params.get("api_key") or request.headers.get("x-api-key") or request.headers.get("X-API-Key")
+        if not api_key:
+            api_key = await api_key_header.__call__(request)
+        if api_key and api_key in api_keys:
+            return {"method": "api_key", "sub": "api_key_client"}
+        if api_key and auth_store and auth_store.verify_api_key(api_key):
+            return {"method": "api_key", "sub": "api_key_client"}
+
+        # Basic
+        authz = request.headers.get("authorization") or request.headers.get("Authorization")
+        if authz and authz.lower().startswith("basic "):
+            try:
+                b64 = authz.split(" ", 1)[1]
+                raw = base64.b64decode(b64).decode("utf-8")
+                username, _, password = raw.partition(":")
+            except Exception:
+                username, password = "", ""
+            # If SQL store present, try it first; else fall back to configured map
+            if auth_store:
+                uid = auth_store.authenticate_basic(username, password)
+                if uid:
+                    return {"method": "basic", "sub": uid, "username": username}
+            stored = basic_users.get(username)
+            if stored and (stored == password):
+                return {"method": "basic", "sub": username, "username": username}
+
+        # Bearer JWT
+        if authz and authz.lower().startswith("bearer "):
+            token = authz.split(" ", 1)[1]
+            if validator and (validator.jwks_url or validator.hs256_secret):
+                try:
+                    claims = decode_jwt(
+                        token,
+                        issuer=validator.issuer,
+                        audience=validator.audience,
+                        jwks_url=validator.jwks_url,
+                        hs256_secret=validator.hs256_secret,
+                    )
+                    sub = str(claims.get("sub"))
+                    if not sub:
+                        raise HTTPException(status_code=401, detail="Invalid token: no subject")
+                    return {"method": "jwt", "sub": sub, "claims": claims}
+                except Exception as e:
+                    raise HTTPException(status_code=401, detail=f"Invalid token: {e}")
+
+        raise HTTPException(status_code=401, detail="Unauthorized")
+
+    def _path_requires_auth(path: str, method: str) -> bool:
+        method = method.upper()
+        # Always protect core run endpoints
+        if path == "/run" and method == "POST":
+            return True
+        if path == "/run_sse" and method == "POST":
+            return True
+        # Sessions and artifacts under /apps
+        if path.startswith("/apps/"):
+            # Allow metrics to be toggled
+            if path.endswith("/metrics-info") and method == "GET":
+                return cfg.protect_metrics
+            return True
+        # Debug and builder are privileged
+        if path.startswith("/debug/") or path.startswith("/builder/"):
+            return True
+        # API key management endpoints
+        if path.startswith("/auth/api-keys"):
+            return True
+        # Optionally protect list-apps
+        if path == "/list-apps" and method == "GET":
+            return cfg.protect_list_apps
+        return False
+
+    class _AuthMiddleware(BaseHTTPMiddleware):
+        async def dispatch(self, request: Request, call_next):
+            path = request.url.path
+            if not _path_requires_auth(path, request.method):
+                return await call_next(request)
+            # Authenticate
+            try:
+                request.state.identity = await _authenticate(request)
+            except HTTPException as e:
+                from fastapi.responses import JSONResponse
+                return JSONResponse({"detail": e.detail}, status_code=e.status_code)
+            # Optional: Enforce user ownership when path has /users/{user_id}/
+            try:
+                parts = path.strip("/").split("/")
+                if "users" in parts:
+                    idx = parts.index("users")
+                    claimed = parts[idx + 1]
+                    sub = str(request.state.identity.get("sub"))
+                    # Allow api_key method to bypass ownership
+                    if request.state.identity.get("method") != "api_key" and sub != claimed:
+                        from fastapi.responses import JSONResponse
+                        return JSONResponse({"detail": "Forbidden: user mismatch"}, status_code=403)
+            except HTTPException:
+                raise
+            except Exception:
+                pass
+            return await call_next(request)
+
+    app.add_middleware(_AuthMiddleware)
+
+    # Token issuance endpoints (optional)
+    if issuer_cfg and issuer_cfg.enabled:
+        if issuer_cfg.algorithm == "HS256" and not issuer_cfg.hs256_secret:
+            raise RuntimeError("HS256 issuer requires hs256_secret")
+        router = APIRouter()
+
+        @router.post("/auth/register")
+        async def register(username: str, password: str):
+            if not auth_store:
+                raise HTTPException(status_code=400, detail="SQL store not configured")
+            uid = auth_store.create_user(username, password)
+            return {"user_id": uid}
+
+        @router.post("/auth/token")
+        async def token_grant(grant_type: str = "password", username: Optional[str] = None, password: Optional[str] = None,
+                              user_id: Optional[str] = None, fingerprint: Optional[str] = None):
+            sub: Optional[str] = None
+            if grant_type == "password":
+                if not auth_store or not username or password is None:
+                    raise HTTPException(status_code=400, detail="invalid_request")
+                uid = auth_store.authenticate_basic(username, password)
+                if not uid:
+                    raise HTTPException(status_code=401, detail="invalid_grant")
+                sub = uid
+            elif grant_type == "client_credentials":
+                # For simplicity map to provided user_id
+                if not user_id:
+                    raise HTTPException(status_code=400, detail="invalid_request")
+                sub = user_id
+            else:
+                raise HTTPException(status_code=400, detail="unsupported_grant_type")
+
+            now = now_ts()
+            access = {
+                "iss": issuer_cfg.issuer,
+                "aud": issuer_cfg.audience,
+                "sub": sub,
+                "iat": now,
+                "nbf": now,
+                "exp": now + issuer_cfg.access_ttl_seconds,
+            }
+            key = issuer_cfg.hs256_secret if issuer_cfg.algorithm == "HS256" else ""
+            access_token = encode_jwt(access, algorithm=issuer_cfg.algorithm, key=key)
+
+            refresh_token = None
+            if auth_store:
+                jti = auth_store.issue_refresh(sub, issuer_cfg.refresh_ttl_seconds, fingerprint=fingerprint)
+                refresh_token = jti
+            return {"access_token": access_token, "token_type": "bearer", "refresh_token": refresh_token}
+
+        @router.post("/auth/refresh")
+        async def refresh(user_id: str, refresh_token: str, fingerprint: Optional[str] = None):
+            if not auth_store:
+                raise HTTPException(status_code=400, detail="invalid_request")
+            if not auth_store.verify_refresh(refresh_token, user_id, fingerprint=fingerprint):
+                raise HTTPException(status_code=401, detail="invalid_grant")
+            now = now_ts()
+            access = {
+                "iss": issuer_cfg.issuer,
+                "aud": issuer_cfg.audience,
+                "sub": user_id,
+                "iat": now,
+                "nbf": now,
+                "exp": now + issuer_cfg.access_ttl_seconds,
+            }
+            key = issuer_cfg.hs256_secret if issuer_cfg.algorithm == "HS256" else ""
+            access_token = encode_jwt(access, algorithm=issuer_cfg.algorithm, key=key)
+            return {"access_token": access_token, "token_type": "bearer"}
+
+        app.include_router(router)
+
+    # API key management endpoints (require SQL store)
+    if auth_store:
+        api_router = APIRouter()
+
+        @api_router.post("/auth/api-keys")
+        async def create_api_key(user_id: Optional[str] = None, name: Optional[str] = None):
+            key_id, key_plain = auth_store.create_api_key(user_id=user_id, name=name)
+            return {"id": key_id, "api_key": key_plain}
+
+        @api_router.get("/auth/api-keys")
+        async def list_api_keys():
+            return auth_store.list_api_keys()
+
+        @api_router.delete("/auth/api-keys/{key_id}")
+        async def delete_api_key(key_id: str):
+            auth_store.revoke_api_key(key_id)
+            return {"ok": True}
+
+        app.include_router(api_router)

google_adk_extras-0.3.1/src/google_adk_extras/auth/config.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class JwtValidatorConfig:
+    # Accept JWTs from external issuers (e.g., Google/Auth0/Okta) or our own issuer
+    jwks_url: Optional[str] = None
+    issuer: Optional[str] = None
+    audience: Optional[str] = None
+    # If you want to validate with an HS256 shared secret (tests/dev)
+    hs256_secret: Optional[str] = None
+
+
+@dataclass
+class JwtIssuerConfig:
+    # Configure our own issuer if we issue tokens
+    enabled: bool = False
+    issuer: str = "https://example-issuer"
+    audience: str = "adk-api"
+    algorithm: str = "HS256"  # HS256 or RS256/ES256 later
+    hs256_secret: Optional[str] = None
+    access_ttl_seconds: int = 3600
+    refresh_ttl_seconds: int = 60 * 60 * 24 * 14
+    # SQL store for users/refresh tokens
+    database_url: Optional[str] = None  # e.g. sqlite:///auth.db
+
+
+@dataclass
+class AuthConfig:
+    # Global toggle
+    enabled: bool = False
+    # Modes
+    allow_no_auth: bool = False  # if True, bypass checks entirely
+    api_keys: List[str] = field(default_factory=list)  # accepted API keys
+    basic_users: dict[str, str] = field(default_factory=dict)  # username -> password (PBKDF2 hash or plaintext for tests)
+    jwt_validator: Optional[JwtValidatorConfig] = None
+    jwt_issuer: Optional[JwtIssuerConfig] = None
+    # Route policy toggles
+    protect_list_apps: bool = True
+    protect_metrics: bool = True
+    # Scopes are advisory; we currently validate presence of a token and subject. Extend as needed.
+