simple-module-api-tokens 0.0.37__py3-none-any.whl

api_tokens/__init__.py

@@ -0,0 +1 @@
+"""ApiTokens module."""

api_tokens/audit.py

@@ -0,0 +1,52 @@
+"""How an api_tokens row is named, and reached, from the audit log.
+
+Create and revoke are recorded by ``AuditMixin`` (the hash and
+``last_used_at`` are excluded on the model). A token is named by its own
+name and display prefix — never by anything secret.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from simple_module_core.audit_links import AuditLink
+from simple_module_db import ALL_TENANTS_OPTION
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api_tokens.constants import ADMIN_URL, AUDIT_LINK_LABEL, AUDIT_LINK_LABEL_KEY, QP_TOKEN
+from api_tokens.models import ApiToken
+
+
+async def resolve_token_labels(db: AsyncSession, ids: list[str]) -> dict[str, str]:
+    """Map token id -> ``name (prefix…)`` for every id that still resolves.
+
+    Read across tenants like the rest of the audit log: the audit screen is a
+    platform view, and the label carries nothing the row itself does not.
+    """
+    parsed: dict[uuid.UUID, str] = {}
+    for raw in ids:
+        try:
+            parsed[uuid.UUID(raw)] = raw
+        except (ValueError, AttributeError, TypeError):
+            continue
+    if not parsed:
+        return {}
+    stmt = (
+        select(ApiToken.id, ApiToken.name, ApiToken.prefix)
+        .where(ApiToken.id.in_(list(parsed)))
+        .execution_options(**{ALL_TENANTS_OPTION: True})
+    )
+    rows = (await db.execute(stmt)).all()
+    return {parsed.get(tid, str(tid)): f"{name} ({prefix}…)" for tid, name, prefix in rows}
+
+
+def build_token_audit_link() -> AuditLink:
+    return AuditLink(
+        entity_type=ApiToken.__name__,
+        url_template=f"{ADMIN_URL}?{QP_TOKEN}={{id}}",
+        label=AUDIT_LINK_LABEL,
+        label_key=AUDIT_LINK_LABEL_KEY,
+        table_name=ApiToken.__tablename__,
+        label_resolver=resolve_token_labels,
+    )

api_tokens/constants.py

@@ -0,0 +1,76 @@
+"""Stable identifiers for the api_tokens module."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Final
+
+from auth.contracts.tokens import PAT_PREFIX, SERVICE_KEY_PREFIX
+
+MODULE_NAME: Final = "ApiTokens"
+MODULE_PACKAGE: Final = "api_tokens"
+LOCALE_NAMESPACE: Final = "api_tokens"
+
+# Modules this one needs registered first: Auth owns the resolver chain,
+# Users owns the accounts a personal token acts for, Settings stores
+# ``max_lifetime_days``.
+MODULE_AUTH: Final = "Auth"
+MODULE_USERS: Final = "Users"
+MODULE_SETTINGS: Final = "Settings"
+
+
+class TokenKind(StrEnum):
+    PERSONAL = "personal"
+    SERVICE = "service"
+
+
+KIND_PREFIX: Final = {TokenKind.PERSONAL: PAT_PREFIX, TokenKind.SERVICE: SERVICE_KEY_PREFIX}
+
+# Secret: 32 random bytes in base62, left-padded to a fixed width so a
+# well-formed token can be recognised without touching the database.
+SECRET_BYTES: Final = 32
+SECRET_LENGTH: Final = 43  # ceil(256 / log2(62))
+DISPLAY_PREFIX_LENGTH: Final = 8
+
+# Prefix is load-bearing on SQLite, which has no per-module schemas.
+TABLE_TOKEN: Final = "api_tokens_token"
+IX_TOKEN_HASH: Final = "ix_api_tokens_token_hash_tenant"
+NAME_MAX_LENGTH: Final = 100
+MAX_SCOPES: Final = 200
+
+# How stale ``last_used_at`` may get before a request rewrites it. Bounds
+# the write load to one conditional UPDATE per token per window.
+LAST_USED_WRITE_INTERVAL_SECONDS: Final = 300
+
+PERM_GROUP: Final = "API tokens"
+PERM_USE: Final = "api_tokens.use"
+PERM_MANAGE: Final = "api_tokens.manage"
+USER_ROLE: Final = "user"
+
+# Roles a service key may never hold: ``admin`` would be the wildcard on a
+# credential with no person behind it.
+FORBIDDEN_SERVICE_ROLES: Final = frozenset({"admin"})
+
+API_PREFIX: Final = "/api/api_tokens"
+VIEW_PREFIX: Final = "/api-tokens"
+ADMIN_VIEW_PREFIX: Final = "/admin/api-tokens"
+# Trailing slash: both index routes are registered at "/" under their prefix.
+USER_URL: Final = f"{VIEW_PREFIX}/"
+ADMIN_URL: Final = f"{ADMIN_VIEW_PREFIX}/"
+
+PAGE_INDEX: Final = "ApiTokens/Index"
+PAGE_ADMIN: Final = "ApiTokens/Admin"
+
+MENU_LABEL: Final = "API tokens"
+MENU_LABEL_KEY: Final = "api_tokens.nav.api_tokens"
+MENU_USER_ORDER: Final = 980
+MENU_ADMIN_ORDER: Final = 130
+MENU_ICON: Final = "key"
+
+AUDIT_LINK_LABEL: Final = "API token"
+AUDIT_LINK_LABEL_KEY: Final = "api_tokens.audit.token"
+QP_TOKEN: Final = "token"
+
+# Expiry presets offered by the pages, in days; the server accepts any whole
+# number of days up to ``max_lifetime_days``.
+EXPIRY_PRESETS_DAYS: Final = (7, 30, 90, 365)

api_tokens/contracts/__init__.py

@@ -0,0 +1,11 @@
+"""api_tokens contracts — public interface for other modules."""
+
+from api_tokens.contracts.schemas import (
+    CreatedToken,
+    PersonalTokenCreate,
+    RevokedCount,
+    ServiceKeyCreate,
+    TokenView,
+)
+
+__all__ = ["CreatedToken", "PersonalTokenCreate", "RevokedCount", "ServiceKeyCreate", "TokenView"]

api_tokens/contracts/schemas.py

@@ -0,0 +1,70 @@
+"""SQLModel DTOs for the api_tokens module — its public surface."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from pydantic import ConfigDict, field_validator
+from sqlmodel import Field, SQLModel
+
+from api_tokens.constants import MAX_SCOPES, NAME_MAX_LENGTH
+
+
+class TokenView(SQLModel):
+    """A token as lists show it. Never carries the secret or its hash."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    kind: str
+    name: str
+    prefix: str
+    scopes: list[str]
+    roles: list[str] = []
+    owner_user_id: uuid.UUID | None = None
+    owner_email: str | None = None
+    tenant_id: str | None = None
+    created_at: datetime | None = None
+    created_by: str | None = None
+    expires_at: datetime
+    last_used_at: datetime | None = None
+    revoked_at: datetime | None = None
+
+
+class CreatedToken(SQLModel):
+    """The one response that carries the plaintext token."""
+
+    token: str
+    item: TokenView
+
+
+class _CreateBase(SQLModel):
+    name: str = Field(min_length=1, max_length=NAME_MAX_LENGTH)
+    scopes: list[str] = Field(min_length=1, max_length=MAX_SCOPES)
+    # Bounded above by the ``max_lifetime_days`` setting, checked in the service.
+    expires_in_days: int = Field(ge=1)
+
+    @field_validator("name")
+    @classmethod
+    def _strip_name(cls, value: str) -> str:
+        stripped = value.strip()
+        if not stripped:
+            raise ValueError("name must not be blank")
+        return stripped
+
+
+class PersonalTokenCreate(_CreateBase):
+    """Create a personal access token for the signed-in user."""
+
+
+class ServiceKeyCreate(_CreateBase):
+    """Create a service key. ``roles`` may not include ``admin``."""
+
+    roles: list[str] = Field(default_factory=list, max_length=50)
+
+
+class RevokedCount(SQLModel):
+    """How many tokens a bulk revoke ended."""
+
+    revoked: int

api_tokens/deps.py

@@ -0,0 +1,66 @@
+"""FastAPI dependencies for the api_tokens module."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Annotated
+
+from auth.contracts.schemas import UserContext
+from auth.contracts.tokens import AUTH_KIND_SESSION
+from fastapi import Depends, HTTPException, Request
+from simple_module_db.deps import get_db
+from simple_module_hosting.i18n_deps import TranslatorDep
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api_tokens.service import ApiTokenService, TokenError
+from api_tokens.settings import ApiTokensSettings
+
+
+async def get_api_token_service(db: AsyncSession = Depends(get_db)) -> ApiTokenService:
+    return ApiTokenService(db)
+
+
+def get_settings(request: Request) -> ApiTokensSettings:
+    return request.app.state.api_tokens.settings
+
+
+async def require_session_principal(request: Request, t: TranslatorDep) -> UserContext:
+    """The signed-in person — refusing any token-authenticated request.
+
+    Tokens may not mint, list or revoke tokens: a leaked token must not be
+    able to make itself permanent by creating a sibling, or hide by revoking
+    the one an administrator would look for. That covers a provider's own
+    bearer credential too (``auth_kind == "bearer"``): a fifteen-minute access
+    token must not become a year-long PAT. Only a cookie session qualifies, so
+    any request carrying an ``Authorization`` header is refused outright.
+    """
+    user = getattr(request.state, "user", None)
+    if user is None:
+        raise HTTPException(status_code=401, detail=t.t("auth.errors.not_authenticated"))
+    if (
+        getattr(user, "auth_kind", None) != AUTH_KIND_SESSION
+        or getattr(user, "scopes", None) is not None
+        or "authorization" in request.headers
+    ):
+        raise HTTPException(status_code=403, detail=t.t("api_tokens.errors.session_required"))
+    return user
+
+
+def user_uuid(user: UserContext, t) -> uuid.UUID:
+    """The signed-in user's id as a UUID; 403 for a principal that is not an account."""
+    try:
+        return uuid.UUID(str(user.id))
+    except (TypeError, ValueError):
+        raise HTTPException(
+            status_code=403, detail=t.t("api_tokens.errors.session_required")
+        ) from None
+
+
+def http_error(t, exc: TokenError) -> HTTPException:
+    """Translate a service refusal into a 422 the pages can show as-is."""
+    return HTTPException(status_code=422, detail=t.t(exc.key, **exc.params))
+
+
+ApiTokenServiceDep = Annotated[ApiTokenService, Depends(get_api_token_service)]
+SettingsDep = Annotated[ApiTokensSettings, Depends(get_settings)]
+SessionPrincipal = Annotated[UserContext, Depends(require_session_principal)]

api_tokens/endpoints/admin_api.py

@@ -0,0 +1,98 @@
+"""JSON API for administrators: every token in the tenant, and service keys.
+
+Session-only and CSRF-checked like the personal API, and gated on
+``api_tokens.manage``. Reads and revokes are tenant-scoped (fail-closed): an
+administrator acts on the active tenant, never one named in the URL.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from simple_module_db import TenantIsolationError
+from simple_module_hosting.csrf import RequiresCsrf
+from simple_module_hosting.i18n_deps import TranslatorDep
+from simple_module_hosting.permissions import RequiresPermission
+
+from api_tokens.constants import FORBIDDEN_SERVICE_ROLES, PERM_MANAGE, TokenKind
+from api_tokens.contracts.schemas import CreatedToken, ServiceKeyCreate, TokenView
+from api_tokens.deps import ApiTokenServiceDep, SettingsDep, http_error, require_session_principal
+from api_tokens.scopes import assignable_roles, assignable_scopes, check_subset
+from api_tokens.service import ApiTokenService, TokenError
+
+router = APIRouter(
+    prefix="/admin",
+    dependencies=[
+        Depends(require_session_principal),
+        Depends(RequiresCsrf()),
+        Depends(RequiresPermission(PERM_MANAGE)),
+    ],
+)
+
+
+async def tenant_token_views(service: ApiTokenService) -> list[TokenView]:
+    tokens = await service.list_tenant()
+    emails = await service.owner_emails(tokens)
+    return [
+        service.to_view(t, emails.get(t.owner_user_id) if t.owner_user_id else None) for t in tokens
+    ]
+
+
+@router.get("/tokens", response_model=list[TokenView])
+async def list_all(service: ApiTokenServiceDep, t: TranslatorDep) -> list[TokenView]:
+    try:
+        return await tenant_token_views(service)
+    except TenantIsolationError:
+        raise HTTPException(
+            status_code=409, detail=t.t("api_tokens.errors.tenant_required")
+        ) from None
+
+
+@router.post("/service-keys", response_model=CreatedToken, status_code=201)
+async def create_service_key(
+    body: ServiceKeyCreate,
+    request: Request,
+    service: ApiTokenServiceDep,
+    settings: SettingsDep,
+    t: TranslatorDep,
+) -> CreatedToken:
+    try:
+        forbidden = sorted(set(body.roles) & FORBIDDEN_SERVICE_ROLES)
+        if forbidden:
+            raise TokenError("api_tokens.errors.role_forbidden", role=forbidden[0])
+        roles = check_subset(
+            body.roles, assignable_roles(request), "api_tokens.errors.role_not_assignable"
+        )
+        scopes = check_subset(
+            body.scopes, await assignable_scopes(request), "api_tokens.errors.scope_not_held"
+        )
+        token, plaintext = await service.create(
+            kind=TokenKind.SERVICE,
+            name=body.name,
+            scopes=scopes,
+            roles=roles,
+            expires_in_days=body.expires_in_days,
+            max_lifetime_days=settings.max_lifetime_days,
+        )
+    except TokenError as exc:
+        raise http_error(t, exc) from None
+    except TenantIsolationError:
+        raise HTTPException(
+            status_code=409, detail=t.t("api_tokens.errors.tenant_required")
+        ) from None
+    return CreatedToken(token=plaintext, item=service.to_view(token))
+
+
+@router.post("/tokens/{token_id}/revoke", response_model=TokenView)
+async def revoke_any(
+    token_id: uuid.UUID, service: ApiTokenServiceDep, t: TranslatorDep
+) -> TokenView:
+    try:
+        token = await service.get_in_tenant(token_id)
+    except TenantIsolationError:
+        token = None
+    if token is None:
+        raise HTTPException(status_code=404, detail=t.t("api_tokens.errors.not_found"))
+    await service.revoke(token)
+    return service.to_view(token)

api_tokens/endpoints/api.py

@@ -0,0 +1,109 @@
+"""JSON API for a user's own personal access tokens.
+
+Session-only (``require_session_principal``) and CSRF-checked on every
+mutation: the pages call these with the session cookie, and a token may never
+manage tokens.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from simple_module_db import TenantIsolationError
+from simple_module_hosting.csrf import RequiresCsrf
+from simple_module_hosting.i18n_deps import TranslatorDep
+from simple_module_hosting.permissions import RequiresPermission
+
+from api_tokens.constants import PERM_USE, TokenKind
+from api_tokens.contracts.schemas import (
+    CreatedToken,
+    PersonalTokenCreate,
+    RevokedCount,
+    TokenView,
+)
+from api_tokens.deps import (
+    ApiTokenServiceDep,
+    SessionPrincipal,
+    SettingsDep,
+    http_error,
+    require_session_principal,
+    user_uuid,
+)
+from api_tokens.scopes import assignable_scopes, check_subset
+from api_tokens.service import TokenError
+
+router = APIRouter(
+    prefix="/tokens",
+    dependencies=[
+        Depends(require_session_principal),
+        Depends(RequiresCsrf()),
+        Depends(RequiresPermission(PERM_USE)),
+    ],
+)
+
+
+@router.get("/", response_model=list[TokenView])
+async def list_tokens(
+    user: SessionPrincipal, service: ApiTokenServiceDep, t: TranslatorDep
+) -> list[TokenView]:
+    tokens = await service.list_for_owner(user_uuid(user, t))
+    return [service.to_view(token) for token in tokens]
+
+
+@router.post("/", response_model=CreatedToken, status_code=201)
+async def create_token(
+    body: PersonalTokenCreate,
+    request: Request,
+    user: SessionPrincipal,
+    service: ApiTokenServiceDep,
+    settings: SettingsDep,
+    t: TranslatorDep,
+) -> CreatedToken:
+    owner = user_uuid(user, t)
+    if not await service.has_usable_account(owner):
+        # No local account the resolver could load (e.g. Keycloak): refuse
+        # instead of minting a token that can never authenticate.
+        raise HTTPException(status_code=400, detail=t.t("api_tokens.errors.account_required"))
+    try:
+        scopes = check_subset(
+            body.scopes, await assignable_scopes(request), "api_tokens.errors.scope_not_held"
+        )
+        token, plaintext = await service.create(
+            kind=TokenKind.PERSONAL,
+            name=body.name,
+            scopes=scopes,
+            expires_in_days=body.expires_in_days,
+            max_lifetime_days=settings.max_lifetime_days,
+            owner_user_id=owner,
+        )
+    except TokenError as exc:
+        raise http_error(t, exc) from None
+    except TenantIsolationError:
+        raise HTTPException(
+            status_code=409, detail=t.t("api_tokens.errors.tenant_required")
+        ) from None
+    return CreatedToken(token=plaintext, item=service.to_view(token))
+
+
+@router.post("/revoke-all", response_model=RevokedCount)
+async def revoke_all_tokens(
+    user: SessionPrincipal, service: ApiTokenServiceDep, t: TranslatorDep
+) -> RevokedCount:
+    """Revoke every personal token the signed-in user holds — the panic button.
+
+    Tokens deliberately survive a password change and "sign out everywhere"
+    (see docs/modules/api_tokens.md, Security model); this is how to end them.
+    """
+    return RevokedCount(revoked=await service.revoke_all_for_owner(user_uuid(user, t)))
+
+
+@router.post("/{token_id}/revoke", response_model=TokenView)
+async def revoke_token(
+    token_id: uuid.UUID, user: SessionPrincipal, service: ApiTokenServiceDep, t: TranslatorDep
+) -> TokenView:
+    token = await service.get_owned(token_id, user_uuid(user, t))
+    if token is None:
+        raise HTTPException(status_code=404, detail=t.t("api_tokens.errors.not_found"))
+    await service.revoke(token, cross_tenant=True)
+    return service.to_view(token)

api_tokens/endpoints/views.py

@@ -0,0 +1,96 @@
+"""Inertia pages: ``/api-tokens/`` (your own tokens), ``/admin/api-tokens/`` (all).
+
+Both pages only render; every change goes through the JSON API with the CSRF
+token handed out here, because the one response carrying a new token's
+secret has to reach the page as data, not as a redirect.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Request
+from simple_module_db import TenantIsolationError
+from simple_module_hosting.csrf import get_csrf_token
+from simple_module_hosting.i18n_deps import TranslatorDep
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.permissions import RequiresPermission
+from simple_module_inertia import InertiaResponse
+
+from api_tokens.constants import (
+    API_PREFIX,
+    EXPIRY_PRESETS_DAYS,
+    PAGE_ADMIN,
+    PAGE_INDEX,
+    PERM_MANAGE,
+    PERM_USE,
+)
+from api_tokens.deps import (
+    ApiTokenServiceDep,
+    SessionPrincipal,
+    SettingsDep,
+    require_session_principal,
+    user_uuid,
+)
+from api_tokens.endpoints.admin_api import tenant_token_views
+from api_tokens.scopes import assignable_roles, assignable_scopes
+
+router = APIRouter(
+    dependencies=[Depends(require_session_principal), Depends(RequiresPermission(PERM_USE))]
+)
+admin_router = APIRouter(
+    dependencies=[Depends(require_session_principal), Depends(RequiresPermission(PERM_MANAGE))]
+)
+
+
+def _form_props(request: Request, max_days: int) -> dict:
+    return {
+        "max_lifetime_days": max_days,
+        "expiry_presets": [d for d in EXPIRY_PRESETS_DAYS if d <= max_days] or [max_days],
+        "csrf_token": get_csrf_token(request),
+        "api_url": API_PREFIX,
+    }
+
+
+@router.get("/", response_model=None)
+async def index(
+    request: Request,
+    inertia: InertiaDep,
+    user: SessionPrincipal,
+    service: ApiTokenServiceDep,
+    settings: SettingsDep,
+    t: TranslatorDep,
+) -> InertiaResponse:
+    tokens = await service.list_for_owner(user_uuid(user, t))
+    return await inertia.render(
+        PAGE_INDEX,
+        {
+            "tokens": [service.to_view(tok).model_dump(mode="json") for tok in tokens],
+            "scopes": await assignable_scopes(request),
+            **_form_props(request, settings.max_lifetime_days),
+        },
+    )
+
+
+@admin_router.get("/", response_model=None)
+async def admin_index(
+    request: Request,
+    inertia: InertiaDep,
+    service: ApiTokenServiceDep,
+    settings: SettingsDep,
+) -> InertiaResponse:
+    try:
+        views = await tenant_token_views(service)
+        tenant_required = False
+    except TenantIsolationError:
+        # Strict tenancy with no active tenant: nothing to list, and nowhere
+        # to create a service key. The page says so instead of a 500.
+        views, tenant_required = [], True
+    return await inertia.render(
+        PAGE_ADMIN,
+        {
+            "tokens": [v.model_dump(mode="json") for v in views],
+            "scopes": await assignable_scopes(request),
+            "roles": assignable_roles(request),
+            "tenant_required": tenant_required,
+            **_form_props(request, settings.max_lifetime_days),
+        },
+    )