pyfastauth 0.1.0__tar.gz

pyfastauth-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# NOTE ON ANCHORING
+# Hatchling's file selection is VCS-aware and honours this file. An unanchored
+# pattern such as `data/` or `versions/` would silently strip packaged assets
+# (templates, static CSS, Alembic revisions) out of the built wheel with no
+# warning. Every pattern below that could collide with a package directory is
+# therefore anchored to the repo root with a leading slash.
+
+# --- Python -----------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+/build/
+/dist/
+/wheels/
+*.egg-info/
+.eggs/
+/.venv/
+/venv/
+
+# --- Tooling caches ---------------------------------------------------------
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+/htmlcov/
+/coverage.xml
+.hypothesis/
+
+# --- Secrets and local config (spec 6.2) ------------------------------------
+.env
+.env.*
+!.env.example
+*.secret
+/secrets/
+
+# --- Local databases (spec 6.2) ---------------------------------------------
+# Anchored: must not match src/fastauth/db/
+/data/
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+*.sqlite
+*.sqlite3
+
+# --- OS / editor ------------------------------------------------------------
+.DS_Store
+.idea/
+*.swp
+
+# --- Project ----------------------------------------------------------------
+# The owner's private specification document. It is the rationale behind every
+# design decision here, but it is not ours to publish: it must never reach a
+# public commit, a GitHub push or a PyPI sdist. The rationale that belongs in
+# the open lives in docs/DECISIONS.md instead.
+#
+# Anchored to the repo root, per the note at the top of this file. `text-*.txt`
+# unanchored would also match any future text-*.txt fixture anywhere under
+# src/fastauth/ and silently drop it from the wheel; the leading slash confines
+# the pattern to this one file at this one location.
+/text-2BF8422D3F8F-1.txt
+
+# JUnit reports written by the CI database-coverage guard.
+/junit-*.xml

pyfastauth-0.1.0/CHANGELOG.md

@@ -0,0 +1,253 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project follows [semantic versioning](https://semver.org/).
+
+While the version is `0.x`, a **minor** version may contain breaking changes;
+they are listed under a `Breaking` heading and never appear in a patch release.
+The meaning of an `auth.yaml` key never changes silently — a format change
+raises `schema_version`, and a version this release does not recognise refuses
+to boot rather than being interpreted optimistically.
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.1.0] — 2026-08-21
+
+First release. Alpha: usable and tested, but the API may still move.
+
+### Added
+
+**Integration**
+
+- `FastAuth(config="auth.yaml")` and `auth.install(app)` — the whole
+  integration. Installing twice raises `AlreadyInstalledError`; a path that
+  already exists on the host application raises `RouteCollisionError` before
+  anything is mounted.
+- Public API: `AuthConfig`, `AuthContext`, `AuthUser`, `FastAuth` from
+  `fastauth`; `OwnedModelMixin`, `OwnedRepository`, `SystemRepository` from
+  `fastauth.ownership`. `py.typed`, `mypy --strict` clean.
+
+**Routes** — 16 declared, mounted according to configuration
+
+- HTML: `GET`/`POST /auth/login`, `GET`/`POST /auth/signup`,
+  `GET /auth/account`, `POST /auth/logout`, `POST /auth/logout-all`.
+- JSON: `POST /auth/api/signup`, `POST /auth/api/login`, `POST /auth/token`,
+  `POST /auth/refresh`, `POST /auth/api/logout`, `POST /auth/api/logout-all`,
+  `GET /auth/me`, `GET /auth/sessions`,
+  `DELETE /auth/sessions/{session_id}`.
+
+**Authentication**
+
+- Argon2 password hashing via `pwdlib`, with transparent rehash when the
+  policy tightens and a configurable length policy.
+- HS256 JWT access tokens with issuer, audience, type, token-version and
+  clock-skew validation, and an algorithm allowlist of exactly one entry.
+- Opaque refresh tokens backed by a server-side session row, rotated on every
+  use, stored only as keyed HMAC fingerprints, with reuse detection.
+- Sliding session expiry with an absolute ceiling
+  (`jwt.session_absolute_ttl`, default 90 days).
+- Cookie and bearer transports, both accepted on a request, with the
+  `Authorization` header taking precedence.
+- Logout, and logout-all with token-version invalidation.
+
+**Authorization**
+
+- Roles and scopes declared in `auth.yaml`, with inheritance and cycle
+  detection at load time.
+- Wildcard scope matching: `contracts:*`, `*:read`, and a global `*`.
+  Mid-string wildcards are rejected at configuration load.
+- `auth.current_user`, `auth.optional_user`, `auth.current_context`,
+  `auth.require_scopes(...)` and `auth.protected_router(...)`.
+- 401 for an absent or invalid credential, 403 for a valid credential without
+  the required scope.
+
+**Ownership**
+
+- `OwnedModelMixin` adds a non-null, indexed `owner_id` column.
+- `OwnedRepository` with `create_for_owner`, `list_for_owner`,
+  `get_for_owner`, `update_for_owner`, `delete_for_owner` and
+  `count_for_owner`. There is no unscoped variant of any of them.
+- Foreign-owned and nonexistent rows are indistinguishable in every method.
+- `SystemRepository.list_all_as_system(session, reason=...)` as the single,
+  audited escape hatch.
+
+**Security**
+
+- HKDF key ring: one key per purpose, derived from `jwt.secret`.
+- Signed, session-bound double-submit CSRF tokens, rotated at login against
+  fixation, enforced on cookie-authenticated requests only.
+- Open-redirect defence with a strict allowlist for `?next=`.
+- Security-header middleware, including a `script-src 'none'` CSP, which never
+  overwrites a header the host application set.
+- Sliding-window rate limiting on login by IP and by identifier hash, signup
+  by IP, and refresh by session. No permanent lockout.
+- `X-Forwarded-For` honoured only from a configured `server.trusted_proxies`.
+- Production hardening rules refuse to boot on an insecure configuration,
+  including a non-null `identity.bootstrap.first_user_role`.
+
+**UI**
+
+- Server-rendered login, signup, account and error pages with a bundled
+  stylesheet. No JavaScript, no build step, and overridable template and
+  static directories.
+
+**Database**
+
+- Async SQLAlchemy 2.x over SQLite and PostgreSQL, with a UUID column type
+  that is native on PostgreSQL, and timezone-aware datetimes enforced at the
+  column boundary.
+- Bundled Alembic migrations. The version table carries the configured table
+  prefix so it cannot collide with the host application's own Alembic state.
+
+**Substituted persistence**
+
+- `FastAuth(user_store=…, session_store=…)` replaces the bundled SQLAlchemy
+  stores. The composition root wires the pair into the `UnitOfWork` that every
+  service already takes, so the service, route and authorization layers run
+  unchanged on a foreign backend (D-30).
+- Substituting **both** builds no SQL engine at all, and `database.url` becomes
+  optional — an application on a non-relational backend is not asked to invent a
+  SQLite URL for a database nobody reads, nor to hold a pool open for the
+  process lifetime. Everything engine-shaped then raises `ConfigurationError`
+  naming the cause: `session_dependency`, `AuthComponents.engine`, and the
+  `fastauth db`, `users` and `sessions` commands. `dispose()` is the deliberate
+  exception, because "nothing to close" is a successful shutdown, and
+  `fastauth doctor` reports its four database checks as warnings rather than
+  failing a correct deployment.
+- Substituting only one keeps the engine; the unit of work then spans two
+  backends and `commit()` acts on the SQL half only. Supported, and documented
+  as the weakest of the three configurations.
+- A backend with no transactions is explicitly supported: `commit()` may be a
+  no-op, "user plus roles" is one write through `UserStore.create(roles=…)`, and
+  multi-write service operations are ordered to fail safe.
+- `AuthComponents.engine` is a property returning the engine provider, or
+  raising `ConfigurationError` when there is none; the nullable provider lives
+  on a new `sql_engine` field. Returning `None` would have surfaced as an
+  `AttributeError` several frames away from the constructor argument that caused
+  it. Anyone tracking `main` before this first release should read
+  `components.sql_engine` where they previously read a nullable
+  `components.engine`.
+
+**MongoDB backend** — `pip install "pyfastauth[mongo]"`
+
+- `fastauth.mongo.build_mongo_stores(...)` accepts a connection string or an
+  already-open `AsyncIOMotorDatabase` and returns a `MongoBackend` carrying a
+  `MongoUserStore`, a `MongoSessionStore`, the collection handles, and the
+  client if this package opened one.
+- Roles are an array on the user document, so creating a user with its roles is
+  a single atomic `insertOne`; refresh rotation is a single-document
+  compare-and-swap, a `findOneAndUpdate` whose filter carries both the expected
+  fingerprint and `revoked_at: null`. Nothing in the backend spans two documents
+  atomically, so it needs no multi-document transactions and therefore **no
+  replica set** — a standalone `mongod` is enough (D-32).
+- MongoDB has no DDL, so `fastauth db upgrade` is meaningless here. Its
+  replacement is `await create_indexes(backend.collections)`, run once per
+  deployment. It is not optional: the unique index on `email` *is* the
+  account-identity rule, and without it two concurrent signups for one address
+  produce two accounts.
+- Timestamps are truncated to BSON's millisecond resolution on write, so a
+  `create()` and a later `get()` agree, and truncated rather than rounded so a
+  derived `expires_at` can only ever move earlier (G-15).
+- See [`docs/mongodb.md`](docs/mongodb.md).
+
+**Store conformance kit** — `pip install "pyfastauth[testing]"`
+
+- `fastauth.testing` ships `UserStoreConformance` and `SessionStoreConformance`
+  as executable specifications of the two persistence protocols, so a third
+  party can prove a MongoDB, DynamoDB, Firestore or Redis backend correct
+  without this project's involvement (D-31). Subclass, supply a `store` fixture,
+  run pytest.
+- The suites cover the semantics that fail silently when implemented wrongly:
+  duplicate-email detection that must not check-then-insert, a rotation that
+  must be a real compare-and-swap, a second `revoke` that must not overwrite the
+  first one's audit trail.
+- `tests/integration/` inherits the same suites, so the bundled SQLAlchemy store
+  is validated by exactly the suite a third party runs and the two cannot drift.
+  The kit itself imports no SQLAlchemy, enforced by an import-linter contract
+  and a static import-closure test.
+- `MutableClock`, `FIXED_NOW`, and the rotation-race seams `ConcurrentRotations`
+  and `SameStoreRotations` are public. `honours_injected_clock` is the single
+  opt-out, for a backend whose timestamps are minted server-side; everything
+  else is required.
+- `pytest` therefore becomes an import of shipped code. It is confined to this
+  subpackage, nothing under `fastauth` imports the subpackage, and it is
+  declared as the `testing` extra rather than a dependency, so a production
+  install never sees it.
+- See [`docs/conformance.md`](docs/conformance.md).
+
+**CLI**
+
+- `fastauth init | config validate | secret generate | doctor |
+  db current|history|upgrade|downgrade | users
+  create|list|grant-role|revoke-role|activate|deactivate | sessions
+  list|revoke|purge-expired | routes | version`.
+- `--config/-c` defaults to `./auth.yaml` and is overridable with
+  `$FASTAUTH_CONFIG`. Exit `0` on success, `1` on a check or validation
+  failure, `2` on a usage error.
+
+**Observability**
+
+- Twelve auditable events with an `@auth.on(...)` decorator. Handlers run
+  after commit and a failing handler is logged and swallowed.
+- Structured logging with field redaction and request-id correlation.
+
+- `fastauth doctor` now cross-checks the cookie attributes against `app.base_url`
+  and `server.auth_mount_path`: `transport.cookie.scheme`, `.domain` and `.path`
+  catch the configurations where login returns 200 and every request after it
+  fails with `missing_token`. `secure: true` over `http://` was previously
+  reported as a clean pass.
+
+### Security
+
+- **`logout-all` failed open on a backend without transactions.**
+  `SessionService.revoke_all` revoked the user's sessions and *then* bumped
+  `token_version`. Under SQL both writes share one transaction and the order is
+  immaterial, but a substituted store may have no multi-document transaction at
+  all — and there, a crash between the two writes left the sessions revoked
+  while every outstanding access JWT stayed cryptographically valid until its
+  own expiry. That is the opposite of what "log out everywhere" has to mean.
+  The order is now reversed: `token_version` is bumped first, so an interrupted
+  logout-all over-invalidates (tokens rejected, some session rows surviving)
+  instead of under-invalidating. Found while implementing D-30; no released
+  version was affected, because this is the first release.
+
+### Known limitations
+
+Documented, not defects. See [`docs/threat-model.md`](docs/threat-model.md).
+
+- The rate limiter is in-process: under *N* workers the effective limit is *N*
+  times the configured one. `fastauth doctor` warns when this combination is
+  used in production.
+- No multi-factor authentication, no email verification, no password reset, no
+  social login, no organisations, no admin dashboard.
+- One signing secret, and no key-rotation mechanism.
+- `SessionRecord.ip_hash` exists in the schema but is never populated; IP
+  hashing is disabled by default, so the column is permanently `NULL` (G-02 in
+  `docs/DECISIONS.md`).
+
+### Deviations from the originating specification
+
+Each is deliberate and recorded in [`docs/DECISIONS.md`](docs/DECISIONS.md).
+
+- Refresh tokens are **opaque**, not JWTs (D-02).
+- Sessions **slide** on refresh, bounded by `jwt.session_absolute_ttl` — a
+  configuration key the specification does not define (D-03).
+- Refresh reuse revokes **only the offending session**, not the whole family
+  (D-04).
+- **Both** transports are accepted on any request, with the header winning; CSRF
+  is enforced from how *this* request authenticated, never from configuration
+  (D-05).
+- `identity.bootstrap.first_user_role` is **fatal** in production (D-07).
+- `POST /auth/token` is mounted by default **only in bearer mode** (D-08).
+- Exception classes carry an `Error` suffix per PEP 8
+  (`InvalidCredentialsError`). The machine-readable `code` values on the wire
+  are unchanged and match specification section 9.3 exactly (D-22).
+- Added configuration keys not in the specification: `jwt.session_absolute_ttl`
+  (D-03), `server.trusted_proxies` (D-18), `sessions.retention`.
+
+[Unreleased]: https://github.com/Aadik1ng/fastauth/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Aadik1ng/fastauth/releases/tag/v0.1.0

pyfastauth-0.1.0/LICENSE

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