keepup-admin 0.2.0__tar.gz → 0.4.0__tar.gz

{keepup_admin-0.2.0/keepup_admin.egg-info → keepup_admin-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keepup-admin
-Version: 0.2.0
+Version: 0.4.0
 Summary: An admin framework over FastAPI: plugins, panel, users, replicas
 Author-email: Fedor Sergeev <fksergeev@gmail.com>
 License-Expression: Apache-2.0
@@ -22,22 +22,46 @@ Requires-Dist: fastapi<1,>=0.128
 Requires-Dist: starlette<2,>=1.3.1
 Requires-Dist: pydantic<3,>=2.11
 Requires-Dist: sqlalchemy<3,>=2.0
-Requires-Dist: psycopg2-binary>=2.9
 Requires-Dist: apscheduler<4,>=3.10
-Requires-Dist: bcrypt<5,>=4.0
-Requires-Dist: pyjwt[crypto]<3,>=2.10
-Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: python-multipart>=0.0.31
 Requires-Dist: PyYAML<7,>=6.0
 Requires-Dist: psutil>=7.0
 Requires-Dist: prometheus-client>=0.24
-Requires-Dist: requests>=2.31
+Requires-Dist: requests>=2.33
 Requires-Dist: httpx>=0.28
+Requires-Dist: cryptography>=50.0
+Requires-Dist: urllib3>=2.8
 Provides-Extra: test
 Requires-Dist: pytest>=8; extra == "test"
 Requires-Dist: pytest-asyncio>=0.24; extra == "test"
 Requires-Dist: pytest-cov>=5; extra == "test"
+Requires-Dist: uvicorn>=0.30; extra == "test"
+Provides-Extra: db
+Requires-Dist: keepup-db>=0.4.0; extra == "db"
+Provides-Extra: auth
+Requires-Dist: keepup-auth>=0.4.0; extra == "auth"
+Provides-Extra: users
+Requires-Dist: keepup-users>=0.4.0; extra == "users"
+Provides-Extra: ui
+Requires-Dist: keepup-ui>=0.4.0; extra == "ui"
+Provides-Extra: audit
+Requires-Dist: keepup-audit>=0.4.0; extra == "audit"
+Provides-Extra: metrics
+Requires-Dist: keepup-metrics>=0.4.0; extra == "metrics"
+Provides-Extra: integration-log
+Requires-Dist: keepup-integration-log>=0.4.0; extra == "integration-log"
+Provides-Extra: panel
+Requires-Dist: keepup-db>=0.4.0; extra == "panel"
+Requires-Dist: keepup-auth>=0.4.0; extra == "panel"
+Requires-Dist: keepup-users>=0.4.0; extra == "panel"
+Requires-Dist: keepup-ui>=0.4.0; extra == "panel"
+Requires-Dist: keepup-audit>=0.4.0; extra == "panel"
+Requires-Dist: keepup-metrics>=0.4.0; extra == "panel"
+Requires-Dist: keepup-integration-log>=0.4.0; extra == "panel"
 Provides-Extra: postgres
-Requires-Dist: asyncpg>=0.31; extra == "postgres"
+Requires-Dist: keepup-postgres>=0.4.0; extra == "postgres"
+Provides-Extra: sqlite
+Requires-Dist: keepup-sqlite>=0.4.0; extra == "sqlite"
 Dynamic: license-file
 
 # keepup
@@ -122,16 +146,17 @@ between replicas needs.
 ## Tests
 
 ```bash
-pip install -e ".[test]"
+pip install -e ".[test]" -e packages/keepup-*
 pytest tests/
 ```
 
 **Install first, then test.** Pointing pytest at the checkout does not work on
 its own: `import keepup` has to resolve, and the directory a clone lands in is
 called `keepup-admin`, so nothing is named `keepup` until the package is
-installed. The `test` extra carries what the suite needs beyond the package —
-notably `cryptography`, which the framework itself never imports and the OIDC
-tests sign tokens with.
+installed. The capabilities are distributions of their own in `packages/` —
+each carries the libraries it needs, and the suite imports them — so a clone
+installs them from the tree; the extras name the same ones for an installation
+from the index.
 
 The suite runs against SQLite with no network, needs no application beside the
 package, and holds a coverage floor declared in `pyproject.toml`. Checks that

{keepup_admin-0.2.0 → keepup_admin-0.4.0}/README.md

@@ -80,16 +80,17 @@ between replicas needs.
 ## Tests
 
 ```bash
-pip install -e ".[test]"
+pip install -e ".[test]" -e packages/keepup-*
 pytest tests/
 ```
 
 **Install first, then test.** Pointing pytest at the checkout does not work on
 its own: `import keepup` has to resolve, and the directory a clone lands in is
 called `keepup-admin`, so nothing is named `keepup` until the package is
-installed. The `test` extra carries what the suite needs beyond the package —
-notably `cryptography`, which the framework itself never imports and the OIDC
-tests sign tokens with.
+installed. The capabilities are distributions of their own in `packages/` —
+each carries the libraries it needs, and the suite imports them — so a clone
+installs them from the tree; the extras name the same ones for an installation
+from the index.
 
 The suite runs against SQLite with no network, needs no application beside the
 package, and holds a coverage floor declared in `pyproject.toml`. Checks that

{keepup_admin-0.2.0 → keepup_admin-0.4.0}/__init__.py

@@ -26,6 +26,12 @@ except Exception:
     # itself, until the applications switch to installing by version.
     __version__ = "0.0.0+source"
 
+# Names that moved into a distribution of their own keep working for one
+# release, and say where they went (keepup-114, keepup-124).
+from keepup import compat as _compat
+
+_compat.install()
+
 __all__ = ["KeepupSettings", "StaticMount", "create_app", "__version__"]
 
 

keepup_admin-0.4.0/admin_trail.py

@@ -0,0 +1,60 @@
+"""What an administrator changed, written into the event log (keepup-67).
+
+The event log is where a deployment looks for who did what, and the framework's
+own administrative surface left nothing there: purging the log, changing the
+panel's sections, their grants and the themes, and switching a plugin's
+decision were visible only in the application log -- which rotates, is shipped
+elsewhere or nowhere, and is not what an operator reads. Each of those now
+writes one event naming the administrator.
+
+The types below are the framework's. Neither they nor the types an application
+declares can be created by hand through `POST /api/events`: a journal the
+watched party can fill with lookalikes is not evidence (keepup/events_api.py).
+
+Writing the trail never fails the action it records: the action has already
+happened, and answering an error for it would only invite a repeat. A trail
+that could not be written is logged as an error.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from keepup import events
+
+logger = logging.getLogger(__name__)
+
+#: What an application may import from this module. Everything else is
+#: internal and may change without notice -- see doc/keepup.md.
+__all__ = [
+    "ADMIN_EVENT_TYPES",
+    "EVENTS_PURGED",
+    "PLUGIN_DECISION_CHANGED",
+    "SECTIONS_CHANGED",
+    "THEMES_CHANGED",
+    "record",
+]
+
+EVENTS_PURGED = "admin_events_purged"
+SECTIONS_CHANGED = "admin_sections_changed"
+THEMES_CHANGED = "admin_themes_changed"
+PLUGIN_DECISION_CHANGED = "admin_plugin_decision_changed"
+
+ADMIN_EVENT_TYPES = (EVENTS_PURGED, SECTIONS_CHANGED, THEMES_CHANGED, PLUGIN_DECISION_CHANGED)
+
+
+def _author(admin: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    admin = admin or {}
+    return {"user_id": admin.get("id"), "username": admin.get("username")}
+
+
+async def record(event_type: str, admin: Optional[Dict[str, Any]], text: str,
+                 **details: Any) -> Optional[int]:
+    """Write one administrative event; the id, or None when it could not be written."""
+    data = {"by": _author(admin), **details}
+    try:
+        return await events.event_manager.create_event(
+            event_type=event_type, event_text=text, event_data=data)
+    except Exception as error:
+        logger.error(f"Could not record {event_type} by {data['by'].get('username')}: {error}")
+        return None
+

keepup_admin-0.4.0/api_docs.py

@@ -0,0 +1,76 @@
+"""The API schema and the documentation pages built from it (keepup-96).
+
+FastAPI serves its OpenAPI schema at /openapi.json to anybody, and the schema
+describes every route of the application -- the administrative ones with their
+parameters and bodies. For somebody outside that is a map of where to knock.
+FastAPI has no notion of who is asking, so the framework takes both routes over:
+
+- the schema answers an administrator only, like every other administrative
+  route of the framework, unless the application opens it on purpose
+  (``KeepupSettings.openapi_public``) or removes it (``openapi_url=None``);
+- the documentation pages stay public shells: they fetch the schema from the
+  browser, with the panel's cookie, so an administrator sees the API and anybody
+  else sees the refusal.
+
+Building the schema in code -- ``app.openapi()``, which ci/generate_openapi.py
+calls -- is untouched: it never went through the route.
+"""
+
+from fastapi import Depends
+from fastapi.openapi.docs import (
+    get_redoc_html,
+    get_swagger_ui_html,
+    get_swagger_ui_oauth2_redirect_html,
+)
+from fastapi.responses import JSONResponse
+
+from keepup.auth.dependencies import get_current_admin
+
+#: What an application may import from this module. Everything else is
+#: internal and may change without notice -- see doc/keepup.md.
+__all__ = ["OAUTH2_REDIRECT_URL", "register_api_documentation"]
+
+#: Where Swagger UI returns from an OAuth2 sign-in; FastAPI's own default.
+OAUTH2_REDIRECT_URL = "/docs/oauth2-redirect"
+
+
+def register_api_documentation(app, settings) -> None:
+    """The schema route and the documentation pages, as the settings ask.
+
+    Called right after the application is created: FastAPI used to register
+    these in its constructor, ahead of any route of the application, and a page
+    registered later could be shadowed by a route that happens to match it.
+    """
+    schema_url = settings.openapi_url
+    if not schema_url:
+        # No schema, no pages: they would have nothing to show.
+        return
+
+    if settings.openapi_public:
+        async def api_schema():
+            return JSONResponse(app.openapi())
+    else:
+        async def api_schema(admin: dict = Depends(get_current_admin)):
+            return JSONResponse(app.openapi())
+
+    app.add_api_route(schema_url, api_schema, methods=["GET"], include_in_schema=False)
+
+    if settings.docs_url:
+        async def swagger_page():
+            return get_swagger_ui_html(openapi_url=schema_url, title=f"{app.title} - API",
+                                       oauth2_redirect_url=OAUTH2_REDIRECT_URL)
+
+        async def swagger_redirect():
+            return get_swagger_ui_oauth2_redirect_html()
+
+        app.add_api_route(settings.docs_url, swagger_page, methods=["GET"],
+                          include_in_schema=False)
+        app.add_api_route(OAUTH2_REDIRECT_URL, swagger_redirect, methods=["GET"],
+                          include_in_schema=False)
+
+    if settings.redoc_url:
+        async def redoc_page():
+            return get_redoc_html(openapi_url=schema_url, title=f"{app.title} - API")
+
+        app.add_api_route(settings.redoc_url, redoc_page, methods=["GET"],
+                          include_in_schema=False)

{keepup_admin-0.2.0 → keepup_admin-0.4.0}/audit.py

@@ -22,8 +22,6 @@ from contextlib import asynccontextmanager
 from datetime import datetime
 from typing import Any, Dict, Optional
 
-from sqlalchemy import CheckConstraint, Column, DateTime, Index, Integer, Text, UniqueConstraint
-from sqlalchemy.dialects import postgresql
 
 from keepup import retention, tables
 from keepup.db import DatabaseManagerV2, db_config
@@ -48,6 +46,10 @@ __all__ = [
     "retention_days",
 ]
 
+# The audit capability declares its own tables (keepup-124); re-exported here so
+# the path that predates the catalogue still creates them.
+from keepup_audit.tables import INCOMING_REQUESTS  # noqa: E402
+
 logger = logging.getLogger(__name__)
 
 incoming_requests_buffer: Dict[str, Dict[str, Any]] = {}
@@ -131,6 +133,17 @@ incoming_requests_lock = asyncio.Lock()
 
 BUFFER_FLUSH_INTERVAL = 125
 BUFFER_MAX_SIZE = 100
+#: The most requests the buffer holds, whatever happens to the database
+#: (keepup-68). A failed flush puts its rows back, so with the database away the
+#: buffer used to grow with every request; past this the oldest go.
+BUFFER_HARD_LIMIT = 10_000
+#: After a failed flush, requests do not start another one for this long: the
+#: timed flusher still retries, but not every request on its own.
+FLUSH_RETRY_PAUSE_SECONDS = 5.0
+
+_flush_lock = asyncio.Lock()
+_flush_paused_until = 0.0
+dropped_requests = 0
 #: A request running this long is written without its outcome (keepup-41): the
 #: process that would have finished it has most likely gone.
 IN_FLIGHT_STALE_SECONDS = 3600
@@ -170,7 +183,13 @@ class IncomingRequestLogger:
                 'request_start_at': request_start,
                 'created_at': datetime.utcnow()
             }
-            if len(incoming_requests_buffer) >= BUFFER_MAX_SIZE:
+            global dropped_requests
+            while len(incoming_requests_buffer) > BUFFER_HARD_LIMIT:
+                # Insertion order: the first key is the oldest request.
+                incoming_requests_buffer.pop(next(iter(incoming_requests_buffer)))
+                dropped_requests += 1
+            if (len(incoming_requests_buffer) >= BUFFER_MAX_SIZE and not _flush_lock.locked()
+                    and time.monotonic() >= _flush_paused_until):
                 asyncio.create_task(IncomingRequestLogger.flush_buffer())
 
         return request_id
@@ -231,6 +250,13 @@ class IncomingRequestLogger:
         not grow forever; and at shutdown (``include_in_flight``) everything is
         written -- nothing will finish afterwards.
         """
+        # One flush at a time: a full buffer asked for one on every request.
+        async with _flush_lock:
+            return await IncomingRequestLogger._flush_buffer(include_in_flight, now)
+
+    @staticmethod
+    async def _flush_buffer(include_in_flight: bool, now: Optional[datetime]) -> int:
+        global _flush_paused_until, dropped_requests
         now = now or datetime.utcnow()
         # The buffer lock is taken by the start and the end of every request, so
         # it is held only to pick the rows and take them out -- never across the
@@ -279,6 +305,7 @@ class IncomingRequestLogger:
             # Back into the buffer: the next flush tries again. A request that
             # somehow reappeared meanwhile keeps its newer entry.
             logger.error(f"Error flushing incoming requests buffer: {str(e)}")
+            _flush_paused_until = time.monotonic() + FLUSH_RETRY_PAUSE_SECONDS
             async with incoming_requests_lock:
                 for request_id, req in chosen.items():
                     incoming_requests_buffer.setdefault(request_id, req)
@@ -288,6 +315,10 @@ class IncomingRequestLogger:
         # duplicate alike: an ignored one is already in the table.
         if inserted_count:
             logger.info(f"Flushed {inserted_count} incoming requests to database")
+        if dropped_requests:
+            logger.warning(f"{dropped_requests} incoming requests were dropped from the "
+                           f"audit while it could not be written")
+            dropped_requests = 0
         return inserted_count
 
 
@@ -360,33 +391,6 @@ async def audit_retention_background():
             await asyncio.sleep(AUDIT_ERROR_BACKOFF_SECONDS)
 
 
-INCOMING_REQUESTS = tables.table(
-    "incoming_requests",
-    tables.auto_id(),
-    Column("instance_id", Text, nullable=False),
-    Column("method", Text, nullable=False),
-    Column("endpoint", Text, nullable=False),
-    Column("host", Text, nullable=False),
-    Column("request_data", postgresql.JSONB().with_variant(Text(), "sqlite")),
-    Column("request_start_at", DateTime, nullable=False),
-    Column("request_end_at", DateTime),
-    Column("duration_ms", Integer),
-    Column("http_status", Integer),
-    Column("response_data", postgresql.JSONB().with_variant(Text(), "sqlite")),
-    Column("error_message", Text),
-    Column("created_at", DateTime, server_default=tables.NOW),
-    UniqueConstraint("instance_id", "method", "endpoint", "request_start_at",
-                     name="incoming_requests_instance_method_endpoint_unique").ddl_if(dialect="postgresql"),
-    CheckConstraint("duration_ms >= 0",
-                    name="incoming_requests_check_duration").ddl_if(dialect="postgresql"),
-    CheckConstraint("(http_status IS NULL) OR (http_status >= 100 AND http_status <= 599)",
-                    name="incoming_requests_check_http_status").ddl_if(dialect="postgresql"),
-    Index("incoming_requests_instance_method_endpoint_unique",
-          "instance_id", "method", "endpoint", "request_start_at", unique=True).ddl_if(dialect="sqlite"),
-    Index("idx_incoming_requests_instance_id", "instance_id"),
-    Index("idx_incoming_requests_endpoint", "endpoint"),
-    Index("idx_incoming_requests_created_at", "created_at"),
-)
 
 
 def init_incoming_requests_table():
@@ -408,6 +412,12 @@ async def background_buffer_flusher():
             await asyncio.sleep(10)
 
 
+def _is_refusal(error: BaseException) -> bool:
+    """An HTTP refusal a route raised on purpose, whose text is its answer."""
+    from starlette.exceptions import HTTPException
+    return isinstance(error, HTTPException)
+
+
 @asynccontextmanager
 async def log_api_request(
         method: str,
@@ -434,10 +444,12 @@ async def log_api_request(
 
     except Exception as e:
         if request_id:
+            # A refusal keeps its reason: it is the answer the client was given.
+            # Anything else keeps its kind, not its text (keepup-76).
             await IncomingRequestLogger.end_request(
                 request_id=request_id,
                 duration_ms=int((time.time() - start_time) * 1000),
-                error_message=str(e)
+                error_message=str(e) if _is_refusal(e) else type(e).__name__
             )
         raise
 

{keepup_admin-0.2.0 → keepup_admin-0.4.0}/body_limit.py

@@ -31,6 +31,8 @@ from typing import Optional
 
 from starlette.routing import Match
 
+from keepup.logging_setup import for_log
+
 #: What an application may import from this module. Everything else is
 #: internal and may change without notice -- see doc/keepup.md.
 __all__ = [
@@ -47,7 +49,9 @@ ROUTE_LIMIT_ATTRIBUTE = "keepup_max_body_bytes"
 READS_OWN_BODY_ATTRIBUTE = "keepup_reads_own_body"
 
 _NOT_DECLARED = object()
-_BODY_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
+#: Methods whose requests are not checked. Everything else is: a route declared
+#: with OPTIONS or a custom method beside a write reads its body as well.
+_BODYLESS_METHODS = {"GET", "HEAD"}
 
 
 def declare_limit(endpoint, route: dict) -> None:
@@ -87,7 +91,7 @@ class BodyLimitMiddleware:
         return self.default_limit
 
     async def __call__(self, scope, receive, send):
-        if scope["type"] != "http" or scope.get("method") not in _BODY_METHODS:
+        if scope["type"] != "http" or scope.get("method") in _BODYLESS_METHODS:
             return await self.app(scope, receive, send)
         limit = self.limit_for(scope)
         if limit is None:
@@ -96,7 +100,7 @@ class BodyLimitMiddleware:
         declared = _content_length(scope)
         if declared is not None and declared > limit:
             logger.warning("Request body refused: %s %s declares %s bytes, the route "
-                           "accepts %s", scope.get("method"), scope.get("path"),
+                           "accepts %s", scope.get("method"), for_log(scope.get("path")),
                            declared, limit)
             return await _answer_too_large(send, limit)
 
@@ -112,7 +116,7 @@ class BodyLimitMiddleware:
                     state["over"] = True
                     logger.warning("Request body refused: %s %s passed %s bytes without "
                                    "declaring its length", scope.get("method"),
-                                   scope.get("path"), limit)
+                                   for_log(scope.get("path")), limit)
                     return {"type": "http.disconnect"}
             return message
 

keepup_admin-0.4.0/builtin/audit.py

@@ -0,0 +1,107 @@
+"""The audit: incoming calls, the application's events and the administrator's trail.
+
+Task keepup-111. These live in three modules of the kernel -- ``audit.py``
+(incoming requests, redaction, retention), ``events.py`` (the application's own
+event log) and ``admin_trail.py`` (what an administrator decided) -- and all
+three import SQLAlchemy, so the base bundle cannot be assembled without a
+database library while they stay. The plugin here owns the two tables and
+publishes the two services; the kernel's own trail and the route wrapper reach
+them through the names (``keepup/kernel/observability.py``), not by importing
+these modules.
+
+The routes of the event log and the section that shows it travel with the panel
+(keepup-104); what is here is the recording itself, its retention and the two
+names.
+"""
+
+import logging
+from typing import Any, Dict, List
+
+from keepup.kernel.datasource import SERVICE_DATASOURCE
+from keepup.kernel.descriptor import KIND_OPTIONAL, PluginDescriptor
+from keepup.kernel.observability import SERVICE_AUDIT, SERVICE_EVENTS, Recording
+from keepup.audit import INCOMING_REQUESTS
+from keepup.events import APP_EVENTS
+from keepup.plugins.base import BasePlugin
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["AuditPlugin", "AuditRecording"]
+
+
+class AuditRecording(Recording):
+    """The framework's own recording, behind the kernel's two names.
+
+    It delegates to the modules that already do the work (``keepup.audit``,
+    ``keepup.events``) so that nothing changes for a deployment today; those
+    modules travel into this capability's distribution in keepup-124.
+    """
+
+    def __init__(self, datasource: Any = None):
+        from keepup.audit import IncomingRequestLogger, log_api_request
+
+        super().__init__(start=log_api_request, end=IncomingRequestLogger.end_request,
+                         name="keepup audit")
+
+    def watch(self, emitter: Any) -> None:
+        """Add another emitter, for a capability that keeps events of its own."""
+        self.emitters.append(emitter)
+
+
+class AuditPlugin(BasePlugin):
+    """The capability: two tables, two services and the retention they need."""
+
+    descriptor = PluginDescriptor(
+        id="audit",
+        name="Event audit",
+        version="0.4.0",
+        distribution="keepup-audit",
+        kind=KIND_OPTIONAL,
+        priority=60,
+        provides=("audit>=1", "events>=1"),
+        requires=("datasource>=1",),
+        wants=("locks>=1", "scheduler>=1"),
+        contributions=("routes", "sections", "tables", "events"),
+    )
+
+    def __init__(self, config=None):
+        super().__init__("audit", "Event audit", config)
+
+    def register(self, services):
+        """Publish the recording where there is a data source to write it to.
+
+        Args:
+            services: the runtime's registry.
+        """
+        if services.has(SERVICE_DATASOURCE):
+            self.recording = AuditRecording(services.require(SERVICE_DATASOURCE))
+            services.provide(SERVICE_AUDIT, self.recording, version=1, plugin_id="audit")
+            services.provide(SERVICE_EVENTS, self.recording, version=1, plugin_id="audit")
+
+    async def initialize(self):
+        """Keep the recording published at registration; build one if there is none."""
+        if getattr(self, "recording", None) is None:
+            self.recording = AuditRecording(self.services.require(SERVICE_DATASOURCE))
+        return True
+
+    def get_declared_tables(self):
+        """The two tables this capability owns, declared once, until keepup-124."""
+        return [INCOMING_REQUESTS, APP_EVENTS]
+
+    def get_event_sinks(self) -> List[Any]:
+        """What writes an event down, for the kernel's own trail."""
+        return [self.emit]
+
+    async def emit(self, event_type: str, payload: Dict[str, Any] = None) -> None:
+        """Write one event through the module that still owns the table."""
+        from keepup.events import emit_event
+
+        await emit_event(event_type, payload or {})
+
+    def get_api_routes(self):
+        """No routes yet: the event log's own travel with the panel (keepup-104)."""
+        return []
+
+    def get_handlers(self):
+        """What another plugin may reach instead of importing the audit."""
+        return {"recording": self.recording, "emit": self.emit}

keepup_admin-0.4.0/builtin/auth.py

@@ -0,0 +1,100 @@
+"""Sign-in as a capability: who is calling, and what they may do.
+
+Task keepup-116, first half. The kernel owns the shapes and the two names
+(``keepup/kernel/security.py``, keepup-119); this plugin is a deployment putting
+an answer behind them, and the tables that answer needs -- the panel's sessions
+and the login attempts that throttle a guesser -- belong to it.
+
+The sign-in machinery itself (``auth/routes.py``, ``panel_session.py``,
+``login_throttle.py``, the providers, OIDC and somebody else's identity system)
+travels into this capability's distribution in keepup-124, together with the
+routes, the sockets and the CSRF middleware it contributes. What is here is the
+claim: two services, two tables, and an identity the runtime adopts.
+"""
+
+import logging
+from typing import Any, Dict, List
+
+from keepup.kernel.datasource import SERVICE_DATASOURCE
+from keepup.kernel.descriptor import KIND_OPTIONAL, PluginDescriptor
+from keepup.kernel.security import SERVICE_AUTH, SERVICE_PERMISSIONS, Identity
+from keepup.plugins.base import BasePlugin
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["AuthPlugin", "build_identity"]
+
+
+def build_identity(name: str = "keepup-auth") -> Identity:
+    """The framework's own sign-in, behind the shape the kernel owns.
+
+    Args:
+        name: what to call it in a log line.
+
+    Returns:
+        The identity: how a caller is found, and what decides a right.
+    """
+    from keepup.auth.dependencies import get_panel_user
+    from keepup.auth.identity import access
+
+    return Identity(subject_dependency=get_panel_user, checker=access.check, name=name)
+
+
+class AuthPlugin(BasePlugin):
+    """The capability: sessions, attempts, and the two services that answer."""
+
+    descriptor = PluginDescriptor(
+        id="auth",
+        name="Sign-in and sessions",
+        version="0.4.0",
+        distribution="keepup-auth",
+        kind=KIND_OPTIONAL,
+        priority=30,
+        provides=("auth>=1", "permissions>=1"),
+        requires=("datasource>=1",),
+        contributions=("routes", "sockets", "middleware", "tables", "permissions"),
+    )
+
+    def __init__(self, config=None):
+        super().__init__("auth", "Sign-in and sessions", config)
+
+    def register(self, services):
+        """Publish the identity under both names, once there is storage.
+
+        Args:
+            services: the runtime's registry.
+        """
+        if services.has(SERVICE_DATASOURCE):
+            self.identity = build_identity()
+            services.provide(SERVICE_AUTH, self.identity, version=1, plugin_id="auth")
+            services.provide(SERVICE_PERMISSIONS, self.identity, version=1, plugin_id="auth")
+
+    async def initialize(self):
+        """Keep the identity published at registration; build one if there is none."""
+        if getattr(self, "identity", None) is None:
+            self.identity = build_identity()
+        return True
+
+    def get_declared_tables(self) -> List[Any]:
+        """The two tables this capability owns, declared once, until keepup-124."""
+        from keepup.auth.login_throttle import LOGIN_ATTEMPTS
+        from keepup.auth.panel_session import AUTH_SESSION
+
+        return [AUTH_SESSION, LOGIN_ATTEMPTS]
+
+    def get_route_permissions(self) -> Dict[str, Any]:
+        """The rights this capability's routes ask for, by name.
+
+        Empty here, and declared all the same: the kind of contribution is what
+        another plugin reads to know that a right it asks for exists.
+        """
+        return {}
+
+    def get_api_routes(self) -> List[Any]:
+        """No routes yet: the sign-in's own (sign in, out, refresh, WebSocket, CSRF)
+        travel into this capability's distribution in keepup-124."""
+        return []
+
+    def get_handlers(self) -> Dict[str, Any]:
+        """What another plugin may reach instead of importing the sign-in."""
+        return {"identity": self.identity}