kernia-mongo 0.1.0__tar.gz

kernia_mongo-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.uv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Docs build output
+/site/
+docs/site/
+
+# Internal tooling (not part of the public repo)
+scripts/audit_layout.py
+scripts/setup_kernia_dns.sh
+spec/
+
+# Local
+
+.projects/cache
+.projects/vault
+.projects/state.test.json
+.projects/state.local.test.json
+.env
+.env.local
+.env.test

kernia_mongo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Advantch
+
+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.

kernia_mongo-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: kernia-mongo
+Version: 0.1.0
+Summary: MongoDB adapter for Kernia (motor)
+Project-URL: Homepage, https://kernia.dev
+Project-URL: Documentation, https://kernia.dev/docs
+Project-URL: Source, https://github.com/advantch/kernia
+Project-URL: Issues, https://github.com/advantch/kernia/issues
+Project-URL: Changelog, https://github.com/advantch/kernia/releases
+Author: Advantch
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asgi,authentication,authorization,django,fastapi,oauth,passkeys,security,sessions,sso,starlette
+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: Topic :: Internet :: WWW/HTTP :: Session
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: kernia>=0.1.0
+Requires-Dist: motor>=3
+Description-Content-Type: text/markdown
+
+# kernia-mongo
+
+MongoDB database adapter for Kernia, built on the async `motor` driver.
+
+Part of [Kernia](https://kernia.dev), a framework-agnostic authentication library for Python.
+
+## Installation
+
+    pip install kernia-mongo
+
+## Usage
+
+The adapter is an async factory: connect it, then pass it as `database`.
+
+```python
+from kernia.auth import init
+from kernia.plugins import email_and_password
+from kernia.types.init_options import KerniaOptions
+from kernia_mongo import mongo_adapter
+
+adapter = await mongo_adapter(url="mongodb://localhost:27017", db_name="app")
+
+auth = init(
+    KerniaOptions(
+        database=adapter,
+        secret="dev-secret",
+        plugins=[email_and_password()],
+    )
+)
+```
+
+## Documentation
+
+Full documentation at [kernia.dev/docs](https://kernia.dev/docs). Source at [github.com/advantch/kernia](https://github.com/advantch/kernia).
+
+## License
+
+MIT

kernia_mongo-0.1.0/README.md

@@ -0,0 +1,38 @@
+# kernia-mongo
+
+MongoDB database adapter for Kernia, built on the async `motor` driver.
+
+Part of [Kernia](https://kernia.dev), a framework-agnostic authentication library for Python.
+
+## Installation
+
+    pip install kernia-mongo
+
+## Usage
+
+The adapter is an async factory: connect it, then pass it as `database`.
+
+```python
+from kernia.auth import init
+from kernia.plugins import email_and_password
+from kernia.types.init_options import KerniaOptions
+from kernia_mongo import mongo_adapter
+
+adapter = await mongo_adapter(url="mongodb://localhost:27017", db_name="app")
+
+auth = init(
+    KerniaOptions(
+        database=adapter,
+        secret="dev-secret",
+        plugins=[email_and_password()],
+    )
+)
+```
+
+## Documentation
+
+Full documentation at [kernia.dev/docs](https://kernia.dev/docs). Source at [github.com/advantch/kernia](https://github.com/advantch/kernia).
+
+## License
+
+MIT

kernia_mongo-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "kernia-mongo"
+version = "0.1.0"
+description = "MongoDB adapter for Kernia (motor)"
+requires-python = ">=3.11"
+dependencies = [
+    "kernia>=0.1.0",
+    "motor>=3",
+]
+readme = "README.md"
+license = "MIT"
+license-files = [
+    "LICENSE",
+]
+authors = [
+    {name = "Advantch"},
+]
+keywords = [
+    "authentication",
+    "authorization",
+    "sessions",
+    "oauth",
+    "passkeys",
+    "sso",
+    "asgi",
+    "fastapi",
+    "starlette",
+    "django",
+    "security",
+]
+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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP :: Session",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://kernia.dev"
+Documentation = "https://kernia.dev/docs"
+Source = "https://github.com/advantch/kernia"
+Issues = "https://github.com/advantch/kernia/issues"
+Changelog = "https://github.com/advantch/kernia/releases"
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kernia_mongo"]

kernia_mongo-0.1.0/src/kernia_mongo/__init__.py

@@ -0,0 +1,7 @@
+"""MongoDB adapter for Kernia."""
+
+from __future__ import annotations
+
+from kernia_mongo.adapter import MongoAdapter, mongo_adapter, where_to_bson
+
+__all__ = ["MongoAdapter", "mongo_adapter", "where_to_bson"]

kernia_mongo-0.1.0/src/kernia_mongo/adapter.py

@@ -0,0 +1,347 @@
+"""MongoDB adapter — implements `CustomAdapter`, `ConsumingAdapter`, `SchemaAdapter`.
+
+Wraps `motor.motor_asyncio.AsyncIOMotorClient`. Stores the better-auth `id` field
+in MongoDB's `_id` column and translates between them transparently so callers never
+see the underlying naming.
+
+Mirrors `reference/packages/mongo-adapter/src/mongodb-adapter.ts`.
+"""
+
+from __future__ import annotations
+
+import re
+import secrets
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from kernia.db.schema import CORE_MODELS
+from kernia.types.adapter import (
+    ConsumingAdapter,
+    CustomAdapter,
+    FieldDef,
+    JoinConfig,
+    ModelDef,
+    Record,
+    SchemaAdapter,
+    SortBy,
+    Where,
+)
+
+# ---------------------------------------------------------------------------
+# WhereOp -> BSON filter translator (pure function — heavily unit-tested)
+# ---------------------------------------------------------------------------
+
+
+_REGEX_META = re.compile(r"[.\*\+\?\^\$\{\}\(\)\|\[\]\\]")
+
+
+def _escape_regex(s: str, max_length: int = 256) -> str:
+    """Escape regex special chars for safe `$regex` use."""
+    return _REGEX_META.sub(lambda m: "\\" + m.group(0), s[:max_length])
+
+
+def _field_name(field: str) -> str:
+    """Map adapter-facing field names to MongoDB column names.
+
+    Only `id` is renamed (to `_id`); everything else is passed through.
+    """
+    return "_id" if field == "id" else field
+
+
+def _clause_to_bson(clause: Where) -> dict[str, Any]:
+    """Translate one Where clause to a MongoDB filter fragment."""
+    field = _field_name(clause.field)
+    val = clause.value
+    op = clause.operator
+    match op:
+        case "eq":
+            return {field: val}
+        case "ne":
+            return {field: {"$ne": val}}
+        case "lt":
+            return {field: {"$lt": val}}
+        case "lte":
+            return {field: {"$lte": val}}
+        case "gt":
+            return {field: {"$gt": val}}
+        case "gte":
+            return {field: {"$gte": val}}
+        case "in":
+            return {field: {"$in": list(val)}}
+        case "not_in":
+            return {field: {"$nin": list(val)}}
+        case "contains":
+            return {field: {"$regex": f".*{_escape_regex(str(val))}.*"}}
+        case "starts_with":
+            return {field: {"$regex": f"^{_escape_regex(str(val))}"}}
+        case "ends_with":
+            return {field: {"$regex": f"{_escape_regex(str(val))}$"}}
+        case "ilike_eq":
+            return {field: {"$regex": f"^{_escape_regex(str(val))}$", "$options": "i"}}
+        case _:  # pragma: no cover
+            raise ValueError(f"unsupported operator: {op}")
+
+
+def where_to_bson(where: Sequence[Where]) -> dict[str, Any]:
+    """Translate a Sequence[Where] into a complete BSON filter.
+
+    Groups by connector — clauses with connector="AND" go under `$and`, those with
+    "OR" under `$or`. The first clause's connector is ignored (it has no left side).
+    A single clause is emitted bare without wrapping.
+    """
+    if not where:
+        return {}
+    if len(where) == 1:
+        return _clause_to_bson(where[0])
+    and_parts: list[dict[str, Any]] = []
+    or_parts: list[dict[str, Any]] = []
+    for i, clause in enumerate(where):
+        frag = _clause_to_bson(clause)
+        # First clause has no connector context — treat as AND.
+        if i == 0 or clause.connector == "AND":
+            and_parts.append(frag)
+        else:
+            or_parts.append(frag)
+    out: dict[str, Any] = {}
+    if and_parts:
+        out["$and"] = and_parts
+    if or_parts:
+        out["$or"] = or_parts
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Id <-> _id transparent mapping
+# ---------------------------------------------------------------------------
+
+
+def _to_mongo(data: Record) -> Record:
+    """Map adapter-facing `id` to MongoDB `_id` on insert/update."""
+    if "id" not in data:
+        return dict(data)
+    out = dict(data)
+    out["_id"] = out.pop("id")
+    return out
+
+
+def _from_mongo(doc: dict[str, Any] | None) -> Record | None:
+    """Map MongoDB `_id` to adapter-facing `id` on read."""
+    if doc is None:
+        return None
+    out = dict(doc)
+    if "_id" in out:
+        out["id"] = out.pop("_id")
+    return out
+
+
+def _project(row: Record, select: Sequence[str] | None) -> Record:
+    if not select:
+        return row
+    return {k: row[k] for k in select if k in row}
+
+
+# ---------------------------------------------------------------------------
+# Adapter
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class MongoAdapter:
+    """Motor-backed adapter."""
+
+    db: Any  # AsyncIOMotorDatabase — typed as Any to avoid hard dep at type-check time
+    models: tuple[ModelDef, ...] = ()
+
+    def _coll(self, model: str) -> Any:
+        return self.db[model]
+
+    async def create(
+        self,
+        *,
+        model: str,
+        data: Record,
+        select: Sequence[str] | None = None,
+    ) -> Record:
+        row = dict(data)
+        row.setdefault("id", secrets.token_urlsafe(16))
+        row.setdefault("createdAt", int(time.time()))
+        row.setdefault("updatedAt", int(time.time()))
+        doc = _to_mongo(row)
+        await self._coll(model).insert_one(doc)
+        out = _from_mongo(doc)
+        assert out is not None
+        return _project(out, select)
+
+    async def find_one(
+        self,
+        *,
+        model: str,
+        where: Sequence[Where],
+        select: Sequence[str] | None = None,
+        join: JoinConfig | None = None,
+    ) -> Record | None:
+        filt = where_to_bson(where)
+        doc = await self._coll(model).find_one(filt)
+        out = _from_mongo(doc)
+        if out is None:
+            return None
+        result = _project(out, select)
+        if join is not None:
+            foreign = await self.find_one(
+                model=join.model,
+                where=(Where(field=join.foreign_field, value=out.get(join.on)),),
+            )
+            result[join.as_] = foreign
+        return result
+
+    async def find_many(
+        self,
+        *,
+        model: str,
+        where: Sequence[Where] = (),
+        limit: int | None = None,
+        offset: int | None = None,
+        sort_by: SortBy | None = None,
+        select: Sequence[str] | None = None,
+        join: JoinConfig | None = None,
+    ) -> list[Record]:
+        filt = where_to_bson(where)
+        cursor = self._coll(model).find(filt)
+        if sort_by is not None:
+            mongo_field = _field_name(sort_by.field)
+            direction = -1 if sort_by.direction == "desc" else 1
+            cursor = cursor.sort(mongo_field, direction)
+        if offset:
+            cursor = cursor.skip(offset)
+        if limit is not None:
+            cursor = cursor.limit(limit)
+        docs = await cursor.to_list(length=limit if limit is not None else None)
+        out: list[Record] = []
+        for d in docs:
+            row = _from_mongo(d)
+            assert row is not None
+            row = _project(row, select)
+            if join is not None:
+                row[join.as_] = await self.find_one(
+                    model=join.model,
+                    where=(Where(field=join.foreign_field, value=row.get(join.on)),),
+                )
+            out.append(row)
+        return out
+
+    async def update(
+        self,
+        *,
+        model: str,
+        where: Sequence[Where],
+        update: Record,
+    ) -> Record | None:
+        filt = where_to_bson(where)
+        patch = dict(update)
+        patch["updatedAt"] = int(time.time())
+        doc = await self._coll(model).find_one_and_update(
+            filt,
+            {"$set": patch},
+            return_document=True,  # ReturnDocument.AFTER
+        )
+        # Motor uses pymongo.ReturnDocument; True == AFTER (1)
+        return _from_mongo(doc)
+
+    async def update_many(
+        self,
+        *,
+        model: str,
+        where: Sequence[Where],
+        update: Record,
+    ) -> int:
+        filt = where_to_bson(where)
+        patch = dict(update)
+        patch["updatedAt"] = int(time.time())
+        result = await self._coll(model).update_many(filt, {"$set": patch})
+        return int(result.modified_count)
+
+    async def delete(
+        self,
+        *,
+        model: str,
+        where: Sequence[Where],
+    ) -> None:
+        filt = where_to_bson(where)
+        await self._coll(model).delete_one(filt)
+
+    async def delete_many(
+        self,
+        *,
+        model: str,
+        where: Sequence[Where],
+    ) -> int:
+        filt = where_to_bson(where)
+        result = await self._coll(model).delete_many(filt)
+        return int(result.deleted_count)
+
+    async def count(
+        self,
+        *,
+        model: str,
+        where: Sequence[Where] = (),
+    ) -> int:
+        filt = where_to_bson(where)
+        return int(await self._coll(model).count_documents(filt))
+
+    async def consume_one(
+        self,
+        *,
+        model: str,
+        where: Sequence[Where],
+    ) -> Record | None:
+        filt = where_to_bson(where)
+        doc = await self._coll(model).find_one_and_delete(filt)
+        return _from_mongo(doc)
+
+    async def create_schema(self, *, models: Sequence[ModelDef]) -> None:
+        """Create indexes for fields marked unique.
+
+        MongoDB itself creates collections on first insert, so we only need to
+        materialize the unique constraints up-front. `_id` is implicitly unique.
+        """
+        for model in models:
+            for f in model.fields:
+                if not f.unique:
+                    continue
+                if f.name == "id":
+                    continue  # _id is unique by Mongo's contract
+                await self._coll(model.name).create_index(f.name, unique=True)
+
+
+# Reference the optional Protocols to keep them in the package's import graph and
+# make explicit which contracts MongoAdapter satisfies.
+_PROTOCOLS: tuple[type, ...] = (CustomAdapter, ConsumingAdapter, SchemaAdapter)
+
+
+async def mongo_adapter(
+    *,
+    url: str,
+    db_name: str = "kernia",
+    extra_models: Sequence[ModelDef] = (),
+    **kwargs: Any,
+) -> CustomAdapter:
+    """Build a MongoDB adapter, connect, and materialize core indexes.
+
+    `url` is a standard `mongodb://` URI. `db_name` selects the database within
+    the cluster. Any additional `kwargs` are forwarded to `AsyncIOMotorClient`.
+    """
+    from motor.motor_asyncio import AsyncIOMotorClient  # local import — optional dep
+
+    client = AsyncIOMotorClient(url, **kwargs)
+    db = client[db_name]
+    models = tuple(CORE_MODELS) + tuple(extra_models)
+    adapter = MongoAdapter(db=db, models=models)
+    await adapter.create_schema(models=models)
+    return adapter
+
+
+# Re-exported helper for FieldDef introspection — used by tests.
+def is_unique_field(f: FieldDef) -> bool:
+    return f.unique

kernia_mongo-0.1.0/tests/test_filter_translator.py

@@ -0,0 +1,91 @@
+"""Unit tests for the Where -> BSON translator.
+
+Pure-function tests — no Docker, no I/O. Locks in the wire shape of the BSON
+filters our MongoDB adapter emits.
+"""
+
+from __future__ import annotations
+
+from kernia.types.adapter import Where
+from kernia_mongo.adapter import _escape_regex, _field_name, where_to_bson
+
+
+def test_empty_where_is_empty_filter() -> None:
+    assert where_to_bson(()) == {}
+
+
+def test_single_eq_is_bare() -> None:
+    assert where_to_bson((Where("email", "a@example.com"),)) == {"email": "a@example.com"}
+
+
+def test_id_field_maps_to_underscore_id() -> None:
+    assert where_to_bson((Where("id", "abc"),)) == {"_id": "abc"}
+    assert _field_name("id") == "_id"
+    assert _field_name("userId") == "userId"
+
+
+def test_ne_operator() -> None:
+    assert where_to_bson((Where("name", "x", operator="ne"),)) == {"name": {"$ne": "x"}}
+
+
+def test_numeric_operators() -> None:
+    assert where_to_bson((Where("age", 30, operator="gt"),)) == {"age": {"$gt": 30}}
+    assert where_to_bson((Where("age", 30, operator="gte"),)) == {"age": {"$gte": 30}}
+    assert where_to_bson((Where("age", 30, operator="lt"),)) == {"age": {"$lt": 30}}
+    assert where_to_bson((Where("age", 30, operator="lte"),)) == {"age": {"$lte": 30}}
+
+
+def test_in_and_not_in() -> None:
+    assert where_to_bson((Where("status", ["a", "b"], operator="in"),)) == {
+        "status": {"$in": ["a", "b"]}
+    }
+    assert where_to_bson((Where("status", ["a"], operator="not_in"),)) == {
+        "status": {"$nin": ["a"]}
+    }
+
+
+def test_contains_starts_with_ends_with_escape() -> None:
+    f = where_to_bson((Where("email", "a.b", operator="contains"),))
+    assert f == {"email": {"$regex": ".*a\\.b.*"}}
+    f = where_to_bson((Where("email", "a.b", operator="starts_with"),))
+    assert f == {"email": {"$regex": "^a\\.b"}}
+    f = where_to_bson((Where("email", "a.b", operator="ends_with"),))
+    assert f == {"email": {"$regex": "a\\.b$"}}
+
+
+def test_ilike_eq_uses_case_insensitive_regex() -> None:
+    assert where_to_bson((Where("email", "A@X.com", operator="ilike_eq"),)) == {
+        "email": {"$regex": "^A@X\\.com$", "$options": "i"}
+    }
+
+
+def test_and_connector_groups_under_and() -> None:
+    out = where_to_bson(
+        (
+            Where("name", "x"),
+            Where("age", 30, operator="gt", connector="AND"),
+        )
+    )
+    assert out == {"$and": [{"name": "x"}, {"age": {"$gt": 30}}]}
+
+
+def test_or_connector_groups_under_or() -> None:
+    out = where_to_bson(
+        (
+            Where("name", "x"),
+            Where("name", "y", connector="OR"),
+        )
+    )
+    # First clause's connector is treated as AND; second goes to $or.
+    assert out == {"$and": [{"name": "x"}], "$or": [{"name": "y"}]}
+
+
+def test_escape_regex_escapes_meta_chars() -> None:
+    s = _escape_regex(".*+?^${}()|[]\\")
+    assert s == "\\.\\*\\+\\?\\^\\$\\{\\}\\(\\)\\|\\[\\]\\\\"
+
+
+def test_escape_regex_truncates_to_max_length() -> None:
+    s = _escape_regex("a" * 1000, max_length=10)
+    # 10 'a's, none of which are meta chars.
+    assert s == "a" * 10