hayate-auth 0.1.0__tar.gz

hayate_auth-0.1.0/LICENSE

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

hayate_auth-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: hayate-auth
+Version: 0.1.0
+Summary: Authentication for hayate as a pure fetch(Request) -> Response handler: email+password, sessions, CSRF
+Keywords: hayate,authentication,session,better-auth,workers
+Author: Yusuke Hayashi
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Session
+Requires-Dist: hayate>=0.6.0
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/hayatepy/hayate-auth
+Description-Content-Type: text/markdown
+
+# hayate-auth
+
+Standards-first authentication for [hayate](https://github.com/hayatepy/hayate) —
+a mountable, better-auth-style auth handler built on the WHATWG Request/Response
+model.
+
+> **Status: alpha (0.1.x).** Email+password, sessions, and CSRF are implemented
+> and attack-regression-tested; email verification and OAuth land in 0.2. Not
+> yet security-audited — see [SECURITY.md](SECURITY.md). The internal design
+> memo (Japanese, per project convention) lives in [DESIGN.md](DESIGN.md).
+
+```python
+import os
+
+from hayate import Hayate
+from hayate_auth import Auth
+from hayate_auth.adapters.sqlite import SQLiteAdapter
+
+adapter = SQLiteAdapter("app.db")
+adapter.create_tables()
+
+auth = Auth(secret=os.environ["AUTH_SECRET"], adapter=adapter)
+
+app = Hayate()
+auth.register(app)  # serves /api/auth/* (sign-up, sign-in, session, ...)
+
+@app.get("/me", auth.require_session())
+async def me(c):
+    return c.json(c.get("user"))
+```
+
+The same file runs under any ASGI server and on Cloudflare Python Workers —
+see [examples/todo](examples/todo).
+
+## Endpoints (v0.1)
+
+| Method / path (under `/api/auth`) | Purpose |
+|---|---|
+| POST `/sign-up/email` | Register with email + password, start a session |
+| POST `/sign-in/email` | Verify credentials, start a session |
+| GET `/get-session` | Current `{user, session}` (or nulls) |
+| POST `/sign-out` | Revoke the session server-side |
+
+## Why
+
+- Python has no equivalent of better-auth: a framework-agnostic, self-hosted,
+  schema-owning auth *library*. django-allauth is Django-only; fastapi-users is
+  in maintenance mode.
+- better-auth works on every JS framework because its core is a single
+  `fetch(Request) -> Response` handler. hayate is the only Python framework
+  whose user-facing surface *is* WHATWG Request/Response — so that architecture
+  finally maps 1:1 to Python.
+- Zero-dependency core (its only dependency is hayate, itself zero-dependency).
+  Databases, KDFs, and email are injected protocols.
+
+## Security posture
+
+- Passwords: scrypt at OWASP parameters (N=2^17, r=8, p=1) on every runtime,
+  PBKDF2-HMAC-SHA256 (600k) fallback; PHC-style strings make the backends
+  mutually verifiable. Length-only policy per NIST SP 800-63B.
+- Sessions: opaque 256-bit tokens, only their SHA-256 stored;
+  `__Host-`-prefixed HttpOnly SameSite=Lax cookies on HTTPS.
+- CSRF: SameSite + Origin (RFC 6454) + Fetch Metadata — no token embedding.
+- Sign-in failures are uniform in body and KDF timing (enumeration defense).
+- Coverage ledger: [docs/asvs.md](docs/asvs.md) (OWASP ASVS V6/V7, ratcheted).
+- **You must rate-limit** `/api/auth/*` (hayate middleware or your
+  infrastructure): brute-force throttling is deliberately out of core.
+
+## License
+
+MIT

hayate_auth-0.1.0/README.md

@@ -0,0 +1,71 @@
+# hayate-auth
+
+Standards-first authentication for [hayate](https://github.com/hayatepy/hayate) —
+a mountable, better-auth-style auth handler built on the WHATWG Request/Response
+model.
+
+> **Status: alpha (0.1.x).** Email+password, sessions, and CSRF are implemented
+> and attack-regression-tested; email verification and OAuth land in 0.2. Not
+> yet security-audited — see [SECURITY.md](SECURITY.md). The internal design
+> memo (Japanese, per project convention) lives in [DESIGN.md](DESIGN.md).
+
+```python
+import os
+
+from hayate import Hayate
+from hayate_auth import Auth
+from hayate_auth.adapters.sqlite import SQLiteAdapter
+
+adapter = SQLiteAdapter("app.db")
+adapter.create_tables()
+
+auth = Auth(secret=os.environ["AUTH_SECRET"], adapter=adapter)
+
+app = Hayate()
+auth.register(app)  # serves /api/auth/* (sign-up, sign-in, session, ...)
+
+@app.get("/me", auth.require_session())
+async def me(c):
+    return c.json(c.get("user"))
+```
+
+The same file runs under any ASGI server and on Cloudflare Python Workers —
+see [examples/todo](examples/todo).
+
+## Endpoints (v0.1)
+
+| Method / path (under `/api/auth`) | Purpose |
+|---|---|
+| POST `/sign-up/email` | Register with email + password, start a session |
+| POST `/sign-in/email` | Verify credentials, start a session |
+| GET `/get-session` | Current `{user, session}` (or nulls) |
+| POST `/sign-out` | Revoke the session server-side |
+
+## Why
+
+- Python has no equivalent of better-auth: a framework-agnostic, self-hosted,
+  schema-owning auth *library*. django-allauth is Django-only; fastapi-users is
+  in maintenance mode.
+- better-auth works on every JS framework because its core is a single
+  `fetch(Request) -> Response` handler. hayate is the only Python framework
+  whose user-facing surface *is* WHATWG Request/Response — so that architecture
+  finally maps 1:1 to Python.
+- Zero-dependency core (its only dependency is hayate, itself zero-dependency).
+  Databases, KDFs, and email are injected protocols.
+
+## Security posture
+
+- Passwords: scrypt at OWASP parameters (N=2^17, r=8, p=1) on every runtime,
+  PBKDF2-HMAC-SHA256 (600k) fallback; PHC-style strings make the backends
+  mutually verifiable. Length-only policy per NIST SP 800-63B.
+- Sessions: opaque 256-bit tokens, only their SHA-256 stored;
+  `__Host-`-prefixed HttpOnly SameSite=Lax cookies on HTTPS.
+- CSRF: SameSite + Origin (RFC 6454) + Fetch Metadata — no token embedding.
+- Sign-in failures are uniform in body and KDF timing (enumeration defense).
+- Coverage ledger: [docs/asvs.md](docs/asvs.md) (OWASP ASVS V6/V7, ratcheted).
+- **You must rate-limit** `/api/auth/*` (hayate middleware or your
+  infrastructure): brute-force throttling is deliberately out of core.
+
+## License
+
+MIT

hayate_auth-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["uv_build>=0.9,<1"]
+build-backend = "uv_build"
+
+[project]
+name = "hayate-auth"
+version = "0.1.0"
+description = "Authentication for hayate as a pure fetch(Request) -> Response handler: email+password, sessions, CSRF"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Yusuke Hayashi" }]
+keywords = ["hayate", "authentication", "session", "better-auth", "workers"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Internet :: WWW/HTTP :: Session",
+]
+dependencies = ["hayate>=0.6.0"]
+
+[project.urls]
+Repository = "https://github.com/hayatepy/hayate-auth"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3",
+  "pytest-asyncio>=0.25",
+  "ruff>=0.9",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+extend-exclude = ["spike"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]

hayate_auth-0.1.0/src/hayate_auth/__init__.py

@@ -0,0 +1,25 @@
+"""hayate-auth: authentication for hayate as a pure fetch handler."""
+
+from .adapter import Adapter, Where
+from .auth import Auth
+from .crypto import (
+    CryptoBackend,
+    Pbkdf2Backend,
+    ScryptBackend,
+    UnsupportedHashError,
+    default_backend,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Adapter",
+    "Auth",
+    "CryptoBackend",
+    "Pbkdf2Backend",
+    "ScryptBackend",
+    "UnsupportedHashError",
+    "Where",
+    "__version__",
+    "default_backend",
+]

hayate_auth-0.1.0/src/hayate_auth/_uuid7.py

@@ -0,0 +1,34 @@
+"""UUIDv7 (RFC 9562): time-ordered primary keys for every model.
+
+Python 3.14 ships ``uuid.uuid7``; on 3.12/3.13 this falls back to a compliant
+implementation (48-bit Unix milliseconds + 74 random bits). Within the same
+millisecond the fallback gives no ordering guarantee, which is fine for
+primary keys — the point is coarse time-sortability, not a sequence.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import uuid
+
+if hasattr(uuid, "uuid7"):  # Python 3.14+
+    uuid7 = uuid.uuid7
+else:
+
+    def uuid7() -> uuid.UUID:
+        ts_ms = time.time_ns() // 1_000_000
+        rand = int.from_bytes(os.urandom(10), "big")
+        value = (
+            (ts_ms & 0xFFFF_FFFF_FFFF) << 80
+            | 0x7 << 76
+            | ((rand >> 62) & 0xFFF) << 64
+            | 0b10 << 62
+            | (rand & 0x3FFF_FFFF_FFFF_FFFF)
+        )
+        return uuid.UUID(int=value)
+
+
+def new_id() -> str:
+    """A fresh UUIDv7 in the canonical text form used as primary key."""
+    return str(uuid7())

hayate_auth-0.1.0/src/hayate_auth/adapter.py

@@ -0,0 +1,39 @@
+"""The Adapter protocol (DESIGN §5): minimal model-name + dict CRUD.
+
+Database libraries implement these five methods; everything else in
+hayate-auth is written against them. ``Where`` deliberately supports only
+the four operators the core actually uses.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Literal, NamedTuple, Protocol, runtime_checkable
+
+
+class Where(NamedTuple):
+    field: str
+    value: Any
+    op: Literal["eq", "lt", "gt", "in"] = "eq"
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    async def create(self, model: str, data: dict[str, Any]) -> dict[str, Any]: ...
+
+    async def find_one(self, model: str, where: Sequence[Where]) -> dict[str, Any] | None: ...
+
+    async def find_many(
+        self,
+        model: str,
+        where: Sequence[Where],
+        *,
+        limit: int | None = None,
+        sort: tuple[str, str] | None = None,
+    ) -> list[dict[str, Any]]: ...
+
+    async def update(
+        self, model: str, where: Sequence[Where], data: dict[str, Any]
+    ) -> dict[str, Any] | None: ...
+
+    async def delete(self, model: str, where: Sequence[Where]) -> int: ...

hayate_auth-0.1.0/src/hayate_auth/adapters/sqlite.py

@@ -0,0 +1,142 @@
+"""Reference Adapter on stdlib sqlite3 (DESIGN §5).
+
+A single shared connection guarded by a lock, with every blocking call pushed
+through ``asyncio.to_thread`` (called inline on Pyodide, which has no
+threads). Model and field names are validated against ``schema.MODELS``
+before they are interpolated, which is what makes the SQL composition safe.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sqlite3
+import sys
+import threading
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from ..adapter import Where
+from ..schema import MODELS, SQLITE_SCHEMA
+
+_OPS = {"eq": "=", "lt": "<", "gt": ">"}
+
+
+def _validate(model: str, fields: Sequence[str]) -> None:
+    columns = MODELS.get(model)
+    if columns is None:
+        raise ValueError(f"unknown model {model!r}")
+    for field in fields:
+        if field not in columns:
+            raise ValueError(f"unknown field {model}.{field}")
+
+
+def _where_sql(model: str, where: Sequence[Where]) -> tuple[str, list[Any]]:
+    _validate(model, [w.field for w in where])
+    if not where:
+        return "", []
+    clauses: list[str] = []
+    params: list[Any] = []
+    for w in where:
+        if w.op == "in":
+            values = list(w.value)
+            placeholders = ", ".join("?" * len(values))
+            clauses.append(f'"{w.field}" IN ({placeholders})')
+            params.extend(values)
+        else:
+            clauses.append(f'"{w.field}" {_OPS[w.op]} ?')
+            params.append(w.value)
+    return " WHERE " + " AND ".join(clauses), params
+
+
+class SQLiteAdapter:
+    def __init__(self, path: str = ":memory:") -> None:
+        self._conn = sqlite3.connect(path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        self._lock = threading.Lock()
+
+    def create_tables(self) -> None:
+        """Create the hayate-auth schema. Explicit by design: hayate-auth
+        never mutates a database schema behind your back (DESIGN §4)."""
+        with self._lock, self._conn:
+            self._conn.executescript(SQLITE_SCHEMA)
+
+    def close(self) -> None:
+        self._conn.close()
+
+    async def _run(self, fn: Callable[[], Any]) -> Any:
+        if sys.platform == "emscripten":  # no threads on Pyodide
+            return fn()
+        return await asyncio.to_thread(fn)
+
+    async def create(self, model: str, data: dict[str, Any]) -> dict[str, Any]:
+        _validate(model, list(data))
+        columns = ", ".join(f'"{k}"' for k in data)
+        placeholders = ", ".join("?" * len(data))
+        sql = f'INSERT INTO "{model}" ({columns}) VALUES ({placeholders})'
+        params = list(data.values())
+
+        def run() -> dict[str, Any]:
+            with self._lock, self._conn:
+                self._conn.execute(sql, params)
+            return dict(data)
+
+        return await self._run(run)
+
+    async def find_one(self, model: str, where: Sequence[Where]) -> dict[str, Any] | None:
+        rows = await self.find_many(model, where, limit=1)
+        return rows[0] if rows else None
+
+    async def find_many(
+        self,
+        model: str,
+        where: Sequence[Where],
+        *,
+        limit: int | None = None,
+        sort: tuple[str, str] | None = None,
+    ) -> list[dict[str, Any]]:
+        _validate(model, ())
+        clause, params = _where_sql(model, where)
+        sql = f'SELECT * FROM "{model}"{clause}'
+        if sort is not None:
+            field, direction = sort
+            _validate(model, [field])
+            if direction.lower() not in ("asc", "desc"):
+                raise ValueError(f"sort direction must be asc or desc, got {direction!r}")
+            sql += f' ORDER BY "{field}" {direction.upper()}'
+        if limit is not None:
+            sql += " LIMIT ?"
+            params = [*params, int(limit)]
+
+        def run() -> list[dict[str, Any]]:
+            with self._lock:
+                rows = self._conn.execute(sql, params).fetchall()
+            return [dict(row) for row in rows]
+
+        return await self._run(run)
+
+    async def update(
+        self, model: str, where: Sequence[Where], data: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        _validate(model, list(data))
+        clause, where_params = _where_sql(model, where)
+        assignments = ", ".join(f'"{k}" = ?' for k in data)
+        sql = f'UPDATE "{model}" SET {assignments}{clause}'
+        params = [*data.values(), *where_params]
+
+        def run() -> None:
+            with self._lock, self._conn:
+                self._conn.execute(sql, params)
+
+        await self._run(run)
+        return await self.find_one(model, where)
+
+    async def delete(self, model: str, where: Sequence[Where]) -> int:
+        clause, params = _where_sql(model, where)
+        sql = f'DELETE FROM "{model}"{clause}'
+
+        def run() -> int:
+            with self._lock, self._conn:
+                return self._conn.execute(sql, params).rowcount
+
+        return await self._run(run)

hayate_auth-0.1.0/src/hayate_auth/auth.py

@@ -0,0 +1,107 @@
+"""The Auth core: one pure function, ``fetch(Request) -> Response``
+(DESIGN §3), plus the three sugar helpers an app actually touches.
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Any
+
+from hayate import Context, HTTPException, Middleware, Next, Request, Response, problem
+
+from . import csrf
+from . import session as sessions
+from .adapter import Adapter, Where
+from .crypto import CryptoBackend, default_backend
+from .routes import ROUTES, public_user
+
+
+class Auth:
+    def __init__(
+        self,
+        *,
+        secret: str,
+        adapter: Adapter,
+        crypto: CryptoBackend | None = None,
+        base_path: str = "/api/auth",
+        trusted_origins: tuple[str, ...] | list[str] = (),
+        session_ttl: timedelta = timedelta(days=7),
+    ) -> None:
+        if not secret:
+            raise ValueError("secret must be a non-empty string")
+        if not base_path.startswith("/"):
+            raise ValueError("base_path must start with '/'")
+        self.secret = secret
+        self.adapter = adapter
+        self.crypto = crypto if crypto is not None else default_backend()
+        self.base_path = base_path.rstrip("/")
+        self.trusted_origins = frozenset(trusted_origins)
+        self.session_ttl = session_ttl
+        self._dummy: str | None = None
+
+    # -- the core ----------------------------------------------------------------------
+
+    async def fetch(self, request: Request) -> Response:
+        """Serve one auth API request. I/O happens only through the injected
+        protocols, so tests call this directly with a bare Request."""
+        raw = getattr(request, "raw", request)
+        path = raw.url.pathname
+        if path != self.base_path and not path.startswith(self.base_path + "/"):
+            return problem(404, title="Not Found")
+        sub = path[len(self.base_path) :]
+
+        if raw.method == "POST" and not csrf.is_allowed(raw, self.trusted_origins):
+            return problem(403, title="Cross-origin request rejected")
+
+        handler = ROUTES.get((raw.method, sub))
+        if handler is None:
+            return problem(404, title="Not Found")
+        return await handler(self, raw)
+
+    # -- sugar -------------------------------------------------------------------------
+
+    def register(self, app: Any) -> None:
+        """Mount the auth API: two catch-all routes, nothing else
+        (better-auth's Hono recipe, DESIGN §3.2)."""
+
+        async def auth_handler(c: Context) -> Response:
+            return await self.fetch(c.req)
+
+        pattern = f"{self.base_path}/*"
+        app.on("GET", pattern)(auth_handler)
+        app.on("POST", pattern)(auth_handler)
+
+    def require_session(self) -> Middleware:
+        """Middleware: 401 Problem Details unless a valid session cookie is
+        presented; on success ``c.get("user")`` / ``c.get("session")`` are set."""
+
+        async def require_session_middleware(c: Context, next_: Next) -> None:
+            resolved = await self.get_session(c.req.raw)
+            if resolved is None:
+                raise HTTPException(401, title="Authentication required")
+            user, record = resolved
+            c.set("user", user)
+            c.set("session", record)
+            await next_()
+
+        return require_session_middleware
+
+    async def get_session(self, request: Request) -> tuple[dict[str, Any], dict[str, Any]] | None:
+        """(public user, public session) for the request's cookie, or None."""
+        raw = getattr(request, "raw", request)
+        record = await sessions.resolve_session(self.adapter, raw)
+        if record is None:
+            return None
+        user_row = await self.adapter.find_one("user", [Where("id", record["user_id"])])
+        if user_row is None:
+            return None
+        return public_user(user_row), sessions.public_session(record)
+
+    # -- internals ---------------------------------------------------------------------
+
+    async def _dummy_hash(self) -> str:
+        """A throwaway hash used to equalize sign-in timing for unknown
+        users. Generated once per Auth instance, lazily."""
+        if self._dummy is None:
+            self._dummy = await self.crypto.hash_password("hayate-auth-timing-dummy")
+        return self._dummy

hayate_auth-0.1.0/src/hayate_auth/crypto/__init__.py

@@ -0,0 +1,188 @@
+"""Password KDF backends (DESIGN §8, decided by the 2026-07-22 spike).
+
+Default everywhere is scrypt with OWASP parameters; environments whose
+Pyodide predates the OpenSSL-backed hashlib fall back to PBKDF2-HMAC-SHA256.
+Stored hashes carry a PHC-style algorithm identifier, so verification
+dispatches on the stored string and runtimes can be mixed freely
+(measured cross-runtime known-answer match in docs/research/kdf.md).
+
+The iron rule: no self-built crypto primitives. Everything below calls
+``hashlib`` or WebCrypto.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import hmac
+import os
+import sys
+from typing import Protocol
+
+__all__ = [
+    "CryptoBackend",
+    "Pbkdf2Backend",
+    "ScryptBackend",
+    "UnsupportedHashError",
+    "default_backend",
+]
+
+
+class UnsupportedHashError(Exception):
+    """The stored hash uses an algorithm this runtime cannot verify."""
+
+
+class CryptoBackend(Protocol):
+    async def hash_password(self, password: str) -> str: ...
+
+    async def verify_password(self, password: str, stored: str) -> bool: ...
+
+
+def _b64encode(raw: bytes) -> str:
+    return base64.b64encode(raw).decode("ascii").rstrip("=")
+
+
+def _b64decode(text: str) -> bytes:
+    return base64.b64decode(text + "=" * (-len(text) % 4))
+
+
+async def _off_loop(fn):
+    """Run a CPU-heavy KDF without blocking the event loop.
+
+    Pyodide has no threads, but there each request owns its isolate, so
+    calling inline is acceptable (DESIGN §8).
+    """
+    if sys.platform == "emscripten":
+        return fn()
+    return await asyncio.to_thread(fn)
+
+
+def _have_scrypt() -> bool:
+    return hasattr(hashlib, "scrypt")
+
+
+def _have_pbkdf2() -> bool:
+    return hasattr(hashlib, "pbkdf2_hmac")
+
+
+class ScryptBackend:
+    """scrypt (RFC 7914), OWASP parameters: N=2^17, r=8, p=1, 64 MiB."""
+
+    def __init__(self, *, log_n: int = 17, r: int = 8, p: int = 1, dklen: int = 32) -> None:
+        self.log_n = log_n
+        self.r = r
+        self.p = p
+        self.dklen = dklen
+
+    def _derive(self, password: str, salt: bytes, *, log_n: int, r: int, p: int) -> bytes:
+        return hashlib.scrypt(
+            password.encode("utf-8"),
+            salt=salt,
+            n=1 << log_n,
+            r=r,
+            p=p,
+            dklen=self.dklen,
+            maxmem=2 * 128 * r * (1 << log_n),
+        )
+
+    async def hash_password(self, password: str) -> str:
+        salt = os.urandom(16)
+        derived = await _off_loop(
+            lambda: self._derive(password, salt, log_n=self.log_n, r=self.r, p=self.p)
+        )
+        return (
+            f"$scrypt$ln={self.log_n},r={self.r},p={self.p}"
+            f"${_b64encode(salt)}${_b64encode(derived)}"
+        )
+
+    async def verify_password(self, password: str, stored: str) -> bool:
+        return await verify_phc(password, stored)
+
+
+class Pbkdf2Backend:
+    """PBKDF2-HMAC-SHA256 (RFC 8018), OWASP 600k iterations.
+
+    Uses ``hashlib.pbkdf2_hmac`` when present (it is, on current Pyodide);
+    otherwise derives through WebCrypto ``deriveBits`` on Workers.
+    """
+
+    def __init__(self, *, iterations: int = 600_000, dklen: int = 32) -> None:
+        self.iterations = iterations
+        self.dklen = dklen
+
+    async def _derive(self, password: str, salt: bytes, iterations: int, dklen: int) -> bytes:
+        if _have_pbkdf2():
+            return await _off_loop(
+                lambda: hashlib.pbkdf2_hmac(
+                    "sha256", password.encode("utf-8"), salt, iterations, dklen=dklen
+                )
+            )
+        return await _webcrypto_pbkdf2(password.encode("utf-8"), salt, iterations, dklen)
+
+    async def hash_password(self, password: str) -> str:
+        salt = os.urandom(16)
+        derived = await self._derive(password, salt, self.iterations, self.dklen)
+        return f"$pbkdf2-sha256$i={self.iterations}${_b64encode(salt)}${_b64encode(derived)}"
+
+    async def verify_password(self, password: str, stored: str) -> bool:
+        return await verify_phc(password, stored)
+
+
+async def _webcrypto_pbkdf2(password: bytes, salt: bytes, iterations: int, dklen: int) -> bytes:
+    import js
+    from pyodide.ffi import to_js
+
+    key = await js.crypto.subtle.importKey(
+        "raw", to_js(password), "PBKDF2", False, to_js(["deriveBits"])
+    )
+    algo = to_js(
+        {"name": "PBKDF2", "hash": "SHA-256", "salt": salt, "iterations": iterations},
+        dict_converter=js.Object.fromEntries,
+    )
+    bits = await js.crypto.subtle.deriveBits(algo, key, dklen * 8)
+    return bytes(js.Uint8Array.new(bits).to_py())
+
+
+async def verify_phc(password: str, stored: str) -> bool:
+    """Verify against any hash this package ever wrote, whichever backend
+    wrote it. Raises UnsupportedHashError when the algorithm cannot run here."""
+    parts = stored.split("$")
+    if len(parts) != 5 or parts[0] != "":
+        return False
+    _, algorithm, params, salt_b64, hash_b64 = parts
+    salt = _b64decode(salt_b64)
+    expected = _b64decode(hash_b64)
+
+    if algorithm == "scrypt":
+        if not _have_scrypt():
+            raise UnsupportedHashError("stored hash is scrypt but hashlib.scrypt is unavailable")
+        values = dict(item.split("=") for item in params.split(","))
+        log_n, r, p = int(values["ln"]), int(values["r"]), int(values["p"])
+        derived = await _off_loop(
+            lambda: hashlib.scrypt(
+                password.encode("utf-8"),
+                salt=salt,
+                n=1 << log_n,
+                r=r,
+                p=p,
+                dklen=len(expected),
+                maxmem=2 * 128 * r * (1 << log_n),
+            )
+        )
+    elif algorithm == "pbkdf2-sha256":
+        values = dict(item.split("=") for item in params.split(","))
+        iterations = int(values["i"])
+        backend = Pbkdf2Backend(iterations=iterations, dklen=len(expected))
+        derived = await backend._derive(password, salt, iterations, len(expected))
+    else:
+        raise UnsupportedHashError(f"unknown password hash algorithm {algorithm!r}")
+
+    return hmac.compare_digest(derived, expected)
+
+
+def default_backend() -> CryptoBackend:
+    """Best standard KDF the running interpreter offers (DESIGN §8)."""
+    if _have_scrypt():
+        return ScryptBackend()
+    return Pbkdf2Backend()

hayate_auth-0.1.0/src/hayate_auth/csrf.py

@@ -0,0 +1,28 @@
+"""CSRF via standard headers only (DESIGN §9): Origin (RFC 6454) first,
+W3C Fetch Metadata (Sec-Fetch-Site) as the fallback signal. No token
+embedding — SameSite=Lax cookies are the first line of defense and this
+check is the second.
+"""
+
+from __future__ import annotations
+
+from hayate import Request
+
+_SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+
+def is_allowed(request: Request, trusted_origins: frozenset[str]) -> bool:
+    if request.method in _SAFE_METHODS:
+        return True
+
+    origin = request.headers.get("origin")
+    if origin is not None and origin != "null":
+        return origin == request.url.origin or origin in trusted_origins
+
+    # No Origin header: browsers send Sec-Fetch-Site; non-browser clients
+    # (curl, server-to-server) send neither and cannot carry ambient cookies
+    # in a CSRF-relevant way, so they pass.
+    fetch_site = request.headers.get("sec-fetch-site")
+    if fetch_site is not None:
+        return fetch_site in ("same-origin", "none")
+    return True

hayate_auth-0.1.0/src/hayate_auth/password.py

@@ -0,0 +1,36 @@
+"""Credential policy per NIST SP 800-63B §5.1.1: length is the only rule.
+
+At least 8 characters, no composition rules, and a generous upper bound so
+passphrases and password managers are never punished.
+"""
+
+from __future__ import annotations
+
+MIN_LENGTH = 8
+MAX_LENGTH = 256
+
+
+def password_error(password: object) -> str | None:
+    """None when acceptable, else a human-readable reason."""
+    if not isinstance(password, str):
+        return "Password must be a string"
+    if len(password) < MIN_LENGTH:
+        return f"Password must be at least {MIN_LENGTH} characters"
+    if len(password) > MAX_LENGTH:
+        return f"Password must be at most {MAX_LENGTH} characters"
+    return None
+
+
+def email_error(email: object) -> str | None:
+    """Minimal, standards-agnostic sanity check; real validation is the
+    verification email's job (v0.2)."""
+    if not isinstance(email, str):
+        return "Email must be a string"
+    email = email.strip()
+    if not 3 <= len(email) <= 254 or "@" not in email[1:-1]:
+        return "Email address looks invalid"
+    return None
+
+
+def normalize_email(email: str) -> str:
+    return email.strip().lower()

hayate_auth-0.1.0/src/hayate_auth/routes.py

@@ -0,0 +1,160 @@
+"""The v0.1 endpoint set (DESIGN §7): email sign-up/sign-in, session
+introspection, sign-out. Paths mirror better-auth's API surface.
+
+Every handler is ``(auth, request) -> Response`` over the protocols only —
+no framework object in sight, which is what keeps ``Auth.fetch`` a pure
+function.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from hayate import Headers, Request, Response, problem
+
+from . import session as sessions
+from ._uuid7 import new_id
+from .adapter import Where
+from .password import email_error, normalize_email, password_error
+
+if TYPE_CHECKING:
+    from .auth import Auth
+
+_GENERIC_SIGNIN_FAILURE = "Invalid email or password"
+
+
+def _json_response(data: Any, status: int = 200, cookies: list[str] | None = None) -> Response:
+    headers = Headers({"content-type": "application/json"})
+    for cookie in cookies or ():
+        headers.append("set-cookie", cookie)
+    return Response(json.dumps(data, separators=(",", ":")), status=status, headers=headers)
+
+
+async def _read_json_object(request: Request) -> dict[str, Any] | Response:
+    try:
+        data = await request.json()
+    except Exception:
+        return problem(400, title="Request body must be JSON")
+    if not isinstance(data, dict):
+        return problem(400, title="Request body must be a JSON object")
+    return data
+
+
+def public_user(row: dict[str, Any]) -> dict[str, Any]:
+    user = dict(row)
+    user["email_verified"] = bool(user.get("email_verified"))
+    return user
+
+
+async def _issue_session(auth: Auth, request: Request, user_row: dict[str, Any]) -> Response:
+    token, _ = await sessions.create_session(
+        auth.adapter,
+        user_row["id"],
+        ttl=auth.session_ttl,
+        user_agent=request.headers.get("user-agent"),
+    )
+    cookie = sessions.session_cookie(
+        token,
+        secure=sessions.is_secure_request(request),
+        max_age=int(auth.session_ttl.total_seconds()),
+    )
+    return _json_response({"user": public_user(user_row)}, cookies=[cookie])
+
+
+async def sign_up_email(auth: Auth, request: Request) -> Response:
+    data = await _read_json_object(request)
+    if isinstance(data, Response):
+        return data
+
+    if (error := email_error(data.get("email"))) is not None:
+        return problem(400, title=error)
+    if (error := password_error(data.get("password"))) is not None:
+        return problem(400, title=error)
+    name = data.get("name")
+    if name is not None and not isinstance(name, str):
+        return problem(400, title="Name must be a string")
+
+    email = normalize_email(data["email"])
+    if await auth.adapter.find_one("user", [Where("email", email)]) is not None:
+        return problem(422, title="User already exists")
+
+    stamp = sessions.isoformat(sessions.now())
+    user_row = {
+        "id": new_id(),
+        "email": email,
+        "email_verified": 0,
+        "name": name,
+        "image": None,
+        "created_at": stamp,
+        "updated_at": stamp,
+    }
+    await auth.adapter.create("user", user_row)
+    await auth.adapter.create(
+        "account",
+        {
+            "id": new_id(),
+            "user_id": user_row["id"],
+            "provider_id": "credential",
+            "account_id": user_row["id"],
+            "password_hash": await auth.crypto.hash_password(data["password"]),
+            "access_token": None,
+            "refresh_token": None,
+            "expires_at": None,
+            "created_at": stamp,
+            "updated_at": stamp,
+        },
+    )
+    return await _issue_session(auth, request, user_row)
+
+
+async def sign_in_email(auth: Auth, request: Request) -> Response:
+    data = await _read_json_object(request)
+    if isinstance(data, Response):
+        return data
+    email = data.get("email")
+    password = data.get("password")
+    if not isinstance(email, str) or not isinstance(password, str):
+        return problem(400, title="Email and password are required")
+
+    user_row = await auth.adapter.find_one("user", [Where("email", normalize_email(email))])
+    account = None
+    if user_row is not None:
+        account = await auth.adapter.find_one(
+            "account",
+            [Where("user_id", user_row["id"]), Where("provider_id", "credential")],
+        )
+
+    stored = account["password_hash"] if account else None
+    if user_row is None or stored is None:
+        # Equalize timing against user enumeration (DESIGN §9): burn the
+        # same KDF work a real verification would.
+        await auth.crypto.verify_password(password, await auth._dummy_hash())
+        return problem(401, title=_GENERIC_SIGNIN_FAILURE)
+
+    if not await auth.crypto.verify_password(password, stored):
+        return problem(401, title=_GENERIC_SIGNIN_FAILURE)
+
+    return await _issue_session(auth, request, user_row)
+
+
+async def sign_out(auth: Auth, request: Request) -> Response:
+    await sessions.revoke_session(auth.adapter, request)
+    cookie = sessions.clear_cookie(secure=sessions.is_secure_request(request))
+    return _json_response({"success": True}, cookies=[cookie])
+
+
+async def get_session(auth: Auth, request: Request) -> Response:
+    resolved = await auth.get_session(request)
+    if resolved is None:
+        return _json_response({"session": None, "user": None})
+    user, record = resolved
+    return _json_response({"session": record, "user": user})
+
+
+ROUTES = {
+    ("POST", "/sign-up/email"): sign_up_email,
+    ("POST", "/sign-in/email"): sign_in_email,
+    ("POST", "/sign-out"): sign_out,
+    ("GET", "/get-session"): get_session,
+}

hayate_auth-0.1.0/src/hayate_auth/schema.py

@@ -0,0 +1,77 @@
+"""The four models hayate-auth owns (DESIGN §4), and their SQLite DDL.
+
+Column names are the single source of truth: adapters validate every
+model/field against this table, which is also what makes the naive SQL
+composition in the sqlite adapter injection-safe.
+"""
+
+from __future__ import annotations
+
+MODELS: dict[str, tuple[str, ...]] = {
+    "user": ("id", "email", "email_verified", "name", "image", "created_at", "updated_at"),
+    "session": (
+        "id",
+        "token_hash",
+        "user_id",
+        "expires_at",
+        "ip_address",
+        "user_agent",
+        "created_at",
+    ),
+    "account": (
+        "id",
+        "user_id",
+        "provider_id",
+        "account_id",
+        "password_hash",
+        "access_token",
+        "refresh_token",
+        "expires_at",
+        "created_at",
+        "updated_at",
+    ),
+    "verification": ("id", "identifier", "value_hash", "expires_at", "created_at"),
+}
+
+SQLITE_SCHEMA = """\
+CREATE TABLE IF NOT EXISTS "user" (
+  id TEXT PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE,
+  email_verified INTEGER NOT NULL DEFAULT 0,
+  name TEXT,
+  image TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS "session" (
+  id TEXT PRIMARY KEY,
+  token_hash TEXT NOT NULL UNIQUE,
+  user_id TEXT NOT NULL REFERENCES "user"(id) ON DELETE CASCADE,
+  expires_at TEXT NOT NULL,
+  ip_address TEXT,
+  user_agent TEXT,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS session_user_id ON "session"(user_id);
+CREATE TABLE IF NOT EXISTS "account" (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES "user"(id) ON DELETE CASCADE,
+  provider_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  password_hash TEXT,
+  access_token TEXT,
+  refresh_token TEXT,
+  expires_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE (provider_id, account_id)
+);
+CREATE INDEX IF NOT EXISTS account_user_id ON "account"(user_id);
+CREATE TABLE IF NOT EXISTS "verification" (
+  id TEXT PRIMARY KEY,
+  identifier TEXT NOT NULL,
+  value_hash TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+"""

hayate_auth-0.1.0/src/hayate_auth/session.py

@@ -0,0 +1,119 @@
+"""Opaque session tokens (DESIGN §6).
+
+The cookie carries ``secrets.token_urlsafe(32)``; the database stores only
+its SHA-256, so a leaked database cannot impersonate anyone. Cookie name is
+``__Host-hayate_auth.session`` on HTTPS and falls back to the bare name for
+local plain-HTTP development.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from hayate import Request
+from hayate.cookies import parse_cookies, serialize_set_cookie
+
+from ._uuid7 import new_id
+from .adapter import Adapter, Where
+
+COOKIE_BASE = "hayate_auth.session"
+HOST_COOKIE = f"__Host-{COOKIE_BASE}"
+
+
+def now() -> datetime:
+    return datetime.now(UTC)
+
+
+def isoformat(moment: datetime) -> str:
+    return moment.isoformat(timespec="seconds")
+
+
+def new_token() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def token_hash(token: str) -> str:
+    return hashlib.sha256(token.encode("ascii")).hexdigest()
+
+
+def is_secure_request(request: Request) -> bool:
+    return request.url.protocol == "https:"
+
+
+def read_token(request: Request) -> str | None:
+    header = request.headers.get("cookie")
+    if header is None:
+        return None
+    cookies = parse_cookies(header)
+    return cookies.get(HOST_COOKIE) or cookies.get(COOKIE_BASE)
+
+
+def session_cookie(token: str, *, secure: bool, max_age: int) -> str:
+    return serialize_set_cookie(
+        HOST_COOKIE if secure else COOKIE_BASE,
+        token,
+        max_age=max_age,
+        path="/",
+        secure=secure,
+        http_only=True,
+        same_site="lax",
+    )
+
+
+def clear_cookie(*, secure: bool) -> str:
+    return serialize_set_cookie(
+        HOST_COOKIE if secure else COOKIE_BASE,
+        "",
+        max_age=0,
+        path="/",
+        secure=secure,
+        http_only=True,
+        same_site="lax",
+    )
+
+
+async def create_session(
+    adapter: Adapter, user_id: str, *, ttl: timedelta, user_agent: str | None
+) -> tuple[str, dict[str, Any]]:
+    """Insert a session row and return (cookie token, public row)."""
+    token = new_token()
+    record = {
+        "id": new_id(),
+        "token_hash": token_hash(token),
+        "user_id": user_id,
+        "expires_at": isoformat(now() + ttl),
+        "ip_address": None,
+        "user_agent": user_agent,
+        "created_at": isoformat(now()),
+    }
+    await adapter.create("session", record)
+    return token, record
+
+
+async def resolve_session(adapter: Adapter, request: Request) -> dict[str, Any] | None:
+    """The session row for the request's cookie, or None. Expired rows are
+    deleted on sight."""
+    token = read_token(request)
+    if token is None:
+        return None
+    record = await adapter.find_one("session", [Where("token_hash", token_hash(token))])
+    if record is None:
+        return None
+    if record["expires_at"] <= isoformat(now()):
+        await adapter.delete("session", [Where("id", record["id"])])
+        return None
+    return record
+
+
+async def revoke_session(adapter: Adapter, request: Request) -> None:
+    token = read_token(request)
+    if token is not None:
+        await adapter.delete("session", [Where("token_hash", token_hash(token))])
+
+
+def public_session(record: dict[str, Any]) -> dict[str, Any]:
+    """The wire shape: everything except the token hash."""
+    return {key: value for key, value in record.items() if key != "token_hash"}