domainkit 2.0.0__tar.gz → 2.1.1__tar.gz

{domainkit-2.0.0 → domainkit-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domainkit
-Version: 2.0.0
+Version: 2.1.1
 Summary: A Django-style framework for domain-driven FastAPI services.
 License-Expression: MIT
 License-File: LICENSE
@@ -20,6 +20,7 @@ Classifier: Typing :: Typed
 Provides-Extra: argon2
 Provides-Extra: audit
 Provides-Extra: cloud
+Provides-Extra: devices
 Provides-Extra: granian
 Provides-Extra: httpclient
 Provides-Extra: identity
@@ -56,6 +57,7 @@ Requires-Dist: argon2-cffi (>=25.1.0,<26.0.0) ; extra == "argon2"
 Requires-Dist: asyncpg (>=0.32.0,<1.0.0) ; extra == "postgres"
 Requires-Dist: cryptography (>=50.0.2,<51.0.0) ; extra == "audit"
 Requires-Dist: cryptography (>=50.0.2,<51.0.0) ; extra == "cloud"
+Requires-Dist: cryptography (>=50.0.2,<51.0.0) ; extra == "devices"
 Requires-Dist: cryptography (>=50.0.2,<51.0.0) ; extra == "keys"
 Requires-Dist: cryptography (>=50.0.2,<51.0.0) ; extra == "mfa"
 Requires-Dist: cryptography (>=50.0.2,<51.0.0) ; extra == "pkcs11"
@@ -100,8 +102,8 @@ Requires-Dist: starlette (>=1.8.0,<2.0.0)
 Requires-Dist: tzdata (>=2025.2) ; extra == "tzdata"
 Requires-Dist: uvicorn[standard] (>=0.54.0,<1.0.0)
 Requires-Dist: uvloop (>=0.23.0,<1.0.0) ; (sys_platform != "win32") and (extra == "uvloop")
-Project-URL: Changelog, https://github.com/karimmattar/domainkit/blob/v2.0.0/CHANGELOG.md
-Project-URL: Documentation, https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/reference.md
+Project-URL: Changelog, https://github.com/karimmattar/domainkit/blob/v2.1.1/CHANGELOG.md
+Project-URL: Documentation, https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/reference.md
 Project-URL: Homepage, https://github.com/karimmattar/domainkit
 Project-URL: Issues, https://github.com/karimmattar/domainkit/issues
 Description-Content-Type: text/markdown
@@ -169,71 +171,71 @@ the pages of that release's tag; on GitHub, `main` describes the next
 release, and a release's pages are under its tag
 (`https://github.com/karimmattar/domainkit/tree/vX.Y.Z/docs`).
 
-- [docs/tutorial.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/tutorial.md): getting started, in five
+- [docs/tutorial.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/tutorial.md): getting started, in five
   parts: a first resource, rules, permissions, events and the worker, and
   tests and production; every command and code change run in CI
-- [docs/operations.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/operations.md): running in production:
+- [docs/operations.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/operations.md): running in production:
   processes, configuration, sizing, migrations in a rollout, the worker,
-  sealing, backups, and what to alert on; [docs/runbook.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/runbook.md)
-  for each alarm, [docs/security.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/security.md) the hardening
-  checklist, and [docs/upgrading.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/upgrading.md) from one version
+  sealing, backups, and what to alert on; [docs/runbook.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/runbook.md)
+  for each alarm, [docs/security.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/security.md) the hardening
+  checklist, and [docs/upgrading.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/upgrading.md) from one version
   to the next, and from 0.12 to 1.0
 
-- [docs/reference.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/reference.md): settings, deployment checks,
+- [docs/reference.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/reference.md): settings, deployment checks,
   middleware, errors, the API surface (OpenAPI, versions, deprecations),
   observability, testing, commands, and extension points, a page for each
-- [docs/databases.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/databases.md): several databases, routing,
+- [docs/databases.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/databases.md): several databases, routing,
   sharding, partitioning, and ledgers
-- [docs/queries.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/queries.md): querying repositories,
+- [docs/queries.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/queries.md): querying repositories,
   pages, filters, soft delete, row locks, and savepoints
-- [docs/resources.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/resources.md): aggregates over REST:
+- [docs/resources.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/resources.md): aggregates over REST:
   resource routes, commands and queries, derived schemas, partial changes,
   ETags and conditional writes, field policies, nesting, the generators,
   and the generic admin
-- [docs/runtime.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/runtime.md): how async work runs
+- [docs/runtime.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/runtime.md): how async work runs
   (event loops, background tasks, clean contexts, logging off the loop,
   finding blocking code, free-threaded Python, the shutdown budget,
   readiness, event-handler timeouts, workers and the outbox), running under
   load (request deadlines, load shedding, database timeouts and PgBouncer,
   outgoing HTTP calls), and servers
-- [docs/cache.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/cache.md): caches in memory, Redis, and Valkey,
+- [docs/cache.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/cache.md): caches in memory, Redis, and Valkey,
   and shared rate limits
-- [docs/money.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/money.md): amounts, currencies, rounding, and
+- [docs/money.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/money.md): amounts, currencies, rounding, and
   allocation, and money in tables, queries, and schemas
-- [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/contrib.md): messaging (and workers on RabbitMQ),
+- [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/contrib.md): messaging (and workers on RabbitMQ),
   webhooks, audit and records' history, idempotency, evidence, feature
   flags, keys and encrypted fields, the double-entry ledger, approvals,
   and limits
-- [docs/auth.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/auth.md): users, groups, permissions, content
+- [docs/auth.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/auth.md): users, groups, permissions, content
   types, passwords, backends, tokens, route rules, and the admin API
-- [docs/mail.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/mail.md): email, mail templates, text messages,
+- [docs/mail.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/mail.md): email, mail templates, text messages,
   and push notifications, sent through the outbox
-- [docs/i18n.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/i18n.md): responses in the caller's language,
+- [docs/i18n.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/i18n.md): responses in the caller's language,
   time zones, and number and date formats
-- [docs/uploads.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/uploads.md): file storages, receiving uploads,
+- [docs/uploads.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/uploads.md): file storages, receiving uploads,
   and serving files
-- [docs/live.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/live.md): WebSockets and Server-Sent Events,
+- [docs/live.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/live.md): WebSockets and Server-Sent Events,
   bounded and re-authorized while open, and committed events streamed live
-- [docs/privacy.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/privacy.md): exporting and erasing a person's
+- [docs/privacy.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/privacy.md): exporting and erasing a person's
   data, and retention
-- [docs/testing.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/testing.md): the pytest plugin: test databases,
+- [docs/testing.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/testing.md): the pytest plugin: test databases,
   sync and async clients, factories, a clock to freeze, and query counts
-- [docs/performance.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/performance.md): what a request costs, the
+- [docs/performance.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/performance.md): what a request costs, the
   benchmark ladder CI gates on, and how to make requests cheaper
-- [docs/versioning.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/versioning.md): compatibility, deprecations,
+- [docs/versioning.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/versioning.md): compatibility, deprecations,
   releases, and which releases get security fixes
-- [docs/threat-model.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/threat-model.md): what domainkit protects,
+- [docs/threat-model.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/threat-model.md): what domainkit protects,
   where the trust boundaries are, what it does at each, and what is left to
   a project
-- [docs/fintech.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/fintech.md): a bank's first review, answered: each
+- [docs/fintech.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/fintech.md): a bank's first review, answered: each
   control's page, setting, and test, and `domainkit init --profile fintech`,
   a project with them all on and wired
-- [docs/audit/0.9.0.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/audit/0.9.0.md): the 0.9.0 audit's findings
+- [docs/audit/0.9.0.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/audit/0.9.0.md): the 0.9.0 audit's findings
   that the CHANGELOG names, with their status
-- [docs/api.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/api.md): the public API, module by module, one line a name;
+- [docs/api.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/api.md): the public API, module by module, one line a name;
   `mkdocs.yml` builds these pages into a site, with every name's docstring
 - [docs/adr/](https://github.com/karimmattar/domainkit/tree/main/docs/adr): the decisions behind the design
-- [CHANGELOG.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/CHANGELOG.md) and [SECURITY.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/SECURITY.md)
+- [CHANGELOG.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/CHANGELOG.md) and [SECURITY.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/SECURITY.md)
 
 ## Quick start
 
@@ -279,7 +281,7 @@ grow it. Without `--minimal`, `startdomain` writes a fuller example (notes
 as child entities, an owner, events and a handler, filters); the tutorial
 starts from that one. A route the caller may not reach answers 404, as an unknown path does,
 so check the path first (`/docs` lists every route). `createsuperuser`
-without options asks for each value instead. [docs/tutorial.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/tutorial.md)
+without options asks for each value instead. [docs/tutorial.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/tutorial.md)
 goes on from here, in six parts from a first route: rules written by
 hand, permissions, events run by the worker, and tests.
 
@@ -287,7 +289,7 @@ hand, permissions, events run by the worker, and tests.
 Users, groups, and permissions are installed, requests are authenticated,
 and every route must say who may call it: generated domains need their
 model permissions, and `/auth` and `/admin/auth` log users in and manage
-them ([docs/auth.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/auth.md)).
+them ([docs/auth.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/auth.md)).
 
 
 ```text
@@ -319,13 +321,13 @@ also turn the API docs off, send HSTS for a year, and limit each caller to
 
 Serve it with one worker process per core, each on its own event loop:
 `uvicorn config.asgi:application --workers 4 --loop uvloop`, or Granian
-(`pip install 'domainkit[granian]'`). [docs/reference/servers.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/reference/servers.md)
-gives the whole command with its limits, and [docs/performance.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/performance.md)
+(`pip install 'domainkit[granian]'`). [docs/reference/servers.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/reference/servers.md)
+gives the whole command with its limits, and [docs/performance.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/performance.md)
 how many cores a load needs.
 
 ## Developing domainkit
 
-[CONTRIBUTING.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/CONTRIBUTING.md)
+[CONTRIBUTING.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/CONTRIBUTING.md)
 says how to set up, which checks a change must pass, and how to write it
 up. In short:
 
@@ -375,9 +377,9 @@ not the whole suite. A release reuses the run of its commit's push to
 A full mutation testing run happens weekly, in 17 shards that run side by
 side; each writes its score and the mutants no test caught to its job
 summary. Releases are published to PyPI
-from a version tag; see [docs/versioning.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/versioning.md).
+from a version tag; see [docs/versioning.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/versioning.md).
 
 ## License
 
-MIT; see [LICENSE](https://github.com/karimmattar/domainkit/blob/v2.0.0/LICENSE).
+MIT; see [LICENSE](https://github.com/karimmattar/domainkit/blob/v2.1.1/LICENSE).
 

{domainkit-2.0.0 → domainkit-2.1.1}/README.md

@@ -61,71 +61,71 @@ the pages of that release's tag; on GitHub, `main` describes the next
 release, and a release's pages are under its tag
 (`https://github.com/karimmattar/domainkit/tree/vX.Y.Z/docs`).
 
-- [docs/tutorial.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/tutorial.md): getting started, in five
+- [docs/tutorial.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/tutorial.md): getting started, in five
   parts: a first resource, rules, permissions, events and the worker, and
   tests and production; every command and code change run in CI
-- [docs/operations.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/operations.md): running in production:
+- [docs/operations.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/operations.md): running in production:
   processes, configuration, sizing, migrations in a rollout, the worker,
-  sealing, backups, and what to alert on; [docs/runbook.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/runbook.md)
-  for each alarm, [docs/security.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/security.md) the hardening
-  checklist, and [docs/upgrading.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/upgrading.md) from one version
+  sealing, backups, and what to alert on; [docs/runbook.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/runbook.md)
+  for each alarm, [docs/security.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/security.md) the hardening
+  checklist, and [docs/upgrading.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/upgrading.md) from one version
   to the next, and from 0.12 to 1.0
 
-- [docs/reference.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/reference.md): settings, deployment checks,
+- [docs/reference.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/reference.md): settings, deployment checks,
   middleware, errors, the API surface (OpenAPI, versions, deprecations),
   observability, testing, commands, and extension points, a page for each
-- [docs/databases.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/databases.md): several databases, routing,
+- [docs/databases.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/databases.md): several databases, routing,
   sharding, partitioning, and ledgers
-- [docs/queries.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/queries.md): querying repositories,
+- [docs/queries.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/queries.md): querying repositories,
   pages, filters, soft delete, row locks, and savepoints
-- [docs/resources.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/resources.md): aggregates over REST:
+- [docs/resources.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/resources.md): aggregates over REST:
   resource routes, commands and queries, derived schemas, partial changes,
   ETags and conditional writes, field policies, nesting, the generators,
   and the generic admin
-- [docs/runtime.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/runtime.md): how async work runs
+- [docs/runtime.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/runtime.md): how async work runs
   (event loops, background tasks, clean contexts, logging off the loop,
   finding blocking code, free-threaded Python, the shutdown budget,
   readiness, event-handler timeouts, workers and the outbox), running under
   load (request deadlines, load shedding, database timeouts and PgBouncer,
   outgoing HTTP calls), and servers
-- [docs/cache.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/cache.md): caches in memory, Redis, and Valkey,
+- [docs/cache.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/cache.md): caches in memory, Redis, and Valkey,
   and shared rate limits
-- [docs/money.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/money.md): amounts, currencies, rounding, and
+- [docs/money.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/money.md): amounts, currencies, rounding, and
   allocation, and money in tables, queries, and schemas
-- [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/contrib.md): messaging (and workers on RabbitMQ),
+- [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/contrib.md): messaging (and workers on RabbitMQ),
   webhooks, audit and records' history, idempotency, evidence, feature
   flags, keys and encrypted fields, the double-entry ledger, approvals,
   and limits
-- [docs/auth.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/auth.md): users, groups, permissions, content
+- [docs/auth.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/auth.md): users, groups, permissions, content
   types, passwords, backends, tokens, route rules, and the admin API
-- [docs/mail.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/mail.md): email, mail templates, text messages,
+- [docs/mail.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/mail.md): email, mail templates, text messages,
   and push notifications, sent through the outbox
-- [docs/i18n.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/i18n.md): responses in the caller's language,
+- [docs/i18n.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/i18n.md): responses in the caller's language,
   time zones, and number and date formats
-- [docs/uploads.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/uploads.md): file storages, receiving uploads,
+- [docs/uploads.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/uploads.md): file storages, receiving uploads,
   and serving files
-- [docs/live.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/live.md): WebSockets and Server-Sent Events,
+- [docs/live.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/live.md): WebSockets and Server-Sent Events,
   bounded and re-authorized while open, and committed events streamed live
-- [docs/privacy.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/privacy.md): exporting and erasing a person's
+- [docs/privacy.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/privacy.md): exporting and erasing a person's
   data, and retention
-- [docs/testing.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/testing.md): the pytest plugin: test databases,
+- [docs/testing.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/testing.md): the pytest plugin: test databases,
   sync and async clients, factories, a clock to freeze, and query counts
-- [docs/performance.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/performance.md): what a request costs, the
+- [docs/performance.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/performance.md): what a request costs, the
   benchmark ladder CI gates on, and how to make requests cheaper
-- [docs/versioning.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/versioning.md): compatibility, deprecations,
+- [docs/versioning.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/versioning.md): compatibility, deprecations,
   releases, and which releases get security fixes
-- [docs/threat-model.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/threat-model.md): what domainkit protects,
+- [docs/threat-model.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/threat-model.md): what domainkit protects,
   where the trust boundaries are, what it does at each, and what is left to
   a project
-- [docs/fintech.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/fintech.md): a bank's first review, answered: each
+- [docs/fintech.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/fintech.md): a bank's first review, answered: each
   control's page, setting, and test, and `domainkit init --profile fintech`,
   a project with them all on and wired
-- [docs/audit/0.9.0.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/audit/0.9.0.md): the 0.9.0 audit's findings
+- [docs/audit/0.9.0.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/audit/0.9.0.md): the 0.9.0 audit's findings
   that the CHANGELOG names, with their status
-- [docs/api.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/api.md): the public API, module by module, one line a name;
+- [docs/api.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/api.md): the public API, module by module, one line a name;
   `mkdocs.yml` builds these pages into a site, with every name's docstring
 - [docs/adr/](https://github.com/karimmattar/domainkit/tree/main/docs/adr): the decisions behind the design
-- [CHANGELOG.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/CHANGELOG.md) and [SECURITY.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/SECURITY.md)
+- [CHANGELOG.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/CHANGELOG.md) and [SECURITY.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/SECURITY.md)
 
 ## Quick start
 
@@ -171,7 +171,7 @@ grow it. Without `--minimal`, `startdomain` writes a fuller example (notes
 as child entities, an owner, events and a handler, filters); the tutorial
 starts from that one. A route the caller may not reach answers 404, as an unknown path does,
 so check the path first (`/docs` lists every route). `createsuperuser`
-without options asks for each value instead. [docs/tutorial.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/tutorial.md)
+without options asks for each value instead. [docs/tutorial.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/tutorial.md)
 goes on from here, in six parts from a first route: rules written by
 hand, permissions, events run by the worker, and tests.
 
@@ -179,7 +179,7 @@ hand, permissions, events run by the worker, and tests.
 Users, groups, and permissions are installed, requests are authenticated,
 and every route must say who may call it: generated domains need their
 model permissions, and `/auth` and `/admin/auth` log users in and manage
-them ([docs/auth.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/auth.md)).
+them ([docs/auth.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/auth.md)).
 
 
 ```text
@@ -211,13 +211,13 @@ also turn the API docs off, send HSTS for a year, and limit each caller to
 
 Serve it with one worker process per core, each on its own event loop:
 `uvicorn config.asgi:application --workers 4 --loop uvloop`, or Granian
-(`pip install 'domainkit[granian]'`). [docs/reference/servers.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/reference/servers.md)
-gives the whole command with its limits, and [docs/performance.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/performance.md)
+(`pip install 'domainkit[granian]'`). [docs/reference/servers.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/reference/servers.md)
+gives the whole command with its limits, and [docs/performance.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/performance.md)
 how many cores a load needs.
 
 ## Developing domainkit
 
-[CONTRIBUTING.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/CONTRIBUTING.md)
+[CONTRIBUTING.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/CONTRIBUTING.md)
 says how to set up, which checks a change must pass, and how to write it
 up. In short:
 
@@ -267,8 +267,8 @@ not the whole suite. A release reuses the run of its commit's push to
 A full mutation testing run happens weekly, in 17 shards that run side by
 side; each writes its score and the mutants no test caught to its job
 summary. Releases are published to PyPI
-from a version tag; see [docs/versioning.md](https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/versioning.md).
+from a version tag; see [docs/versioning.md](https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/versioning.md).
 
 ## License
 
-MIT; see [LICENSE](https://github.com/karimmattar/domainkit/blob/v2.0.0/LICENSE).
+MIT; see [LICENSE](https://github.com/karimmattar/domainkit/blob/v2.1.1/LICENSE).

{domainkit-2.0.0 → domainkit-2.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "domainkit"
-version = "2.0.0"
+version = "2.1.1"
 description = "A Django-style framework for domain-driven FastAPI services."
 readme = "README.md"
 license = "MIT"
@@ -53,8 +53,12 @@ jwt = ["pyjwt[crypto] (>=2.15.0,<3.0.0)"]
 # Second factors for domainkit.contrib.auth: AES-GCM for the TOTP secrets
 # it stores (auth.mfa).
 mfa = ["cryptography (>=50.0.2,<51.0.0)"]
+# Passkeys and bound devices (domainkit.contrib.devices, and the sign-in
+# approvals of domainkit.contrib.ciba): their signatures are checked with
+# cryptography.
+devices = ["cryptography (>=50.0.2,<51.0.0)"]
 # Signed checkpoints of the audit trail (AUDIT.CHECKPOINT_KEY, Ed25519):
-# auditprune and auditverify --export.
+# "audit prune" and "audit verify --export".
 audit = ["cryptography (>=50.0.2,<51.0.0)"]
 # Ledgers for evidence (WORM): immudb's SDK, with its verified operations.
 # grpcio for TLS channels, ecdsa's signature error, and protobuf's Empty
@@ -148,8 +152,8 @@ domainkit = "domainkit.management:execute_from_command_line"
 
 [project.urls]
 Homepage = "https://github.com/karimmattar/domainkit"
-Documentation = "https://github.com/karimmattar/domainkit/blob/v2.0.0/docs/reference.md"
-Changelog = "https://github.com/karimmattar/domainkit/blob/v2.0.0/CHANGELOG.md"
+Documentation = "https://github.com/karimmattar/domainkit/blob/v2.1.1/docs/reference.md"
+Changelog = "https://github.com/karimmattar/domainkit/blob/v2.1.1/CHANGELOG.md"
 Issues = "https://github.com/karimmattar/domainkit/issues"
 
 [build-system]

{domainkit-2.0.0 → domainkit-2.1.1}/src/domainkit/apps/config.py

@@ -20,6 +20,11 @@ if TYPE_CHECKING:
     from domainkit.db.routing import DatabaseRouter
 
 CONFIG_MODULE = "apps"
+EXTRAS: Final = {
+    "domainkit.contrib.ciba": "devices",
+    "domainkit.contrib.devices": "devices",
+}
+"""The extra each of domainkit's apps needs to be imported at all, if any."""
 MODELS_MODULE: Final = "models"
 CONTROLLERS_MODULE: Final = "controllers"
 """Where a four-file domain's use cases and ``@handles`` handlers live."""
@@ -249,7 +254,7 @@ def defined_hook_methods(config: DomainConfig) -> list[tuple[str, str]]:
 
 
 def _import_domain(name: str) -> ModuleType:
-    """Import a domain package, explaining a missing one."""
+    """Import a domain package, explaining a missing one, or a missing extra."""
     try:
         module = import_module(name)
     except ModuleNotFoundError as exc:
@@ -259,6 +264,11 @@ def _import_domain(name: str) -> ModuleType:
             raise ImproperlyConfigured(
                 f"Installed domain {name!r} cannot be imported."
             ) from exc
+        if name in EXTRAS:
+            raise ImproperlyConfigured(
+                f"Installed domain {name!r} needs {exc.name!r}, which is not "
+                f'installed: pip install "domainkit[{EXTRAS[name]}]".'
+            ) from exc
         raise
     if not hasattr(module, "__path__"):
         raise ImproperlyConfigured(f"Installed domain {name!r} must be a package.")

{domainkit-2.0.0 → domainkit-2.1.1}/src/domainkit/contrib/auth/api.py

@@ -50,6 +50,7 @@ from .devices import (
     proven_limits,
 )
 from .events import UserLoggedOut
+from .gates import check_gates_passed, pass_login_gates
 from .hashers import acheck_password
 from .models import AbstractBaseUser, UserId
 from .settings import auth_settings
@@ -190,6 +191,7 @@ async def login(
     """Check an identifier and password; return tokens, or a second-factor challenge."""
     _no_store(response)
     user = await check_password(request, body)
+    await pass_login_gates(request, user)
     from .mfa import challenge  # Imports this module.
 
     if (pending := await challenge(user)) is not None:
@@ -278,7 +280,10 @@ async def issue_login(
     """Record the user's login, and issue them tokens (the first class's).
 
     Past ``AUTH.MAX_LOGINS``, the user's oldest logins end. The login is
-    held to what was checked (``held_login``).
+    held to what was checked (``held_login``). A route of the project's
+    that issues a login runs ``pass_login_gates(request, user)`` first:
+    while a login gate is registered, one that skipped them raises
+    ``LoginNotGated``.
     """
     with _acting_as(user):
         async with audited_changes(), AuthUnitOfWork() as uow:
@@ -303,10 +308,15 @@ async def held_login(
     a factor on hold, so a login checked before them and issued after
     never survives them (SEC-16a-6).
 
+    The user passed the login gates first (``gates``): a login that skipped
+    them is refused while any is registered.
+
     Raises:
         AuthenticationFailed: The password changed, or a factor was turned
             on, since the check: the login starts again.
+        LoginNotGated: A gate is registered, and the login skipped them.
     """
+    check_gates_passed(user)
     await uow.tokens.lock_user(user.id)
     stored = await uow.users.get(UserId(user.id))
     if stored.password != user.password or (

{domainkit-2.0.0 → domainkit-2.1.1}/src/domainkit/contrib/auth/apps.py

@@ -197,6 +197,7 @@ class AuthConfig(DomainConfig):
             NotFound: No user has the id.
         """
         from .cookies import cookie_names, start_session
+        from .gates import gates_passed
         from .uow import AuthUnitOfWork
 
         _only_in_tests("issue_test_session")
@@ -209,7 +210,8 @@ class AuthConfig(DomainConfig):
         async with AuthUnitOfWork() as uow:
             user = await uow.users.get(user_id)
         response = Response()
-        started = await start_session(user, response)
+        with gates_passed(user.id):  # A test's session: no request to judge.
+            started = await start_session(user, response)
         cookies: SimpleCookie = SimpleCookie()
         for header in response.headers.getlist("set-cookie"):
             cookies.load(header)

{domainkit-2.0.0 → domainkit-2.1.1}/src/domainkit/contrib/auth/cookies.py

@@ -79,6 +79,7 @@ from .authentication import (
 from .captcha import captcha
 from .devices import hand_out
 from .events import UserLoggedOut
+from .gates import pass_login_gates
 from .mfa import MfaLoginIn, challenge, first_use_after_code, verify_challenge
 from .models import AbstractBaseUser, UserId
 from .principals import forget
@@ -280,6 +281,7 @@ async def log_in(
     _no_store(response)
     check_origin(request)
     user = await check_password(request, body)
+    await pass_login_gates(request, user)
     if (pending := await challenge(user)) is not None:
         response.status_code = status.HTTP_202_ACCEPTED
         return pending  # The device proof waits for the second factor.
@@ -309,6 +311,7 @@ async def log_in_with_code(
     user = await first_use_after_code(
         await verify_challenge(request, body.mfa_token, body.code), body.new_password
     )
+    await pass_login_gates(request, user)
     started = await start_session(user, response, previous=_session_of(request))
     await hand_out(request, response, user)
     return started
@@ -405,6 +408,19 @@ async def start_session(
     return CsrfOut(csrf_token=token)
 
 
+async def start_browser_session(
+    request: Request, user: AbstractBaseUser, response: Response
+) -> CsrfOut:
+    """A browser session for ``user``, whose login was checked another way.
+
+    For apps that log users in by other means (a sign-in approved from
+    the phone): the session the request's cookie held ends, as at
+    ``/session``. Check the request's origin first (``check_origin``),
+    before anything is spent, and run the login gates or pass them.
+    """
+    return await start_session(user, response, previous=_session_of(request))
+
+
 def _session_of(request: Request) -> str | None:
     """The session token a browser's cookie authenticated the request with."""
     credentials = request.scope.get("auth")

domainkit-2.1.1/src/domainkit/contrib/auth/gates.py

@@ -0,0 +1,104 @@
+"""Login gates: checks every login passes before it is issued (ADR 0128).
+
+A domain registers a gate in ``DomainConfig.ready()``. The gate takes the
+request and the user, and raises to refuse the login::
+
+    from domainkit.contrib.auth.gates import on_login_gate
+
+    async def approved_from_the_phone(request: Request, user: AbstractBaseUser) -> None:
+        if not await approved(request, user):
+            raise PhoneApprovalRequired()
+
+    class SignInConfig(DomainConfig):
+        def ready(self) -> None:
+            on_login_gate(approved_from_the_phone)
+
+Every auth route that issues a login calls ``pass_login_gates`` with its
+request and the user before issuing. These are ``/login``, ``/session``,
+``/mfa/login``, ``/session/mfa``, the passkey and device logins, and the
+identity providers' logins. Gates run in ``INSTALLED_DOMAINS`` order, and
+the first that raises refuses the login.
+
+Gates fail closed. While a gate is registered, ``held_login`` refuses a
+login whose user did not pass them in the current context
+(``LoginNotGated``), so a route that forgets the call cannot issue.
+Code that issues a login on the server side, with no request for the
+gates to judge, says so with ``gates_passed(user_id)``. Examples are a
+sign-in approved from a phone and a test's session.
+"""
+
+from collections.abc import Awaitable, Callable, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any, Final
+from uuid import UUID
+
+from starlette.requests import Request
+
+from domainkit.apps.hooks import HookPoint
+from domainkit.exceptions import DomainkitError
+
+from .models import AbstractBaseUser
+
+__all__ = [
+    "LoginGate",
+    "LoginNotGated",
+    "check_gates_passed",
+    "gates_passed",
+    "on_login_gate",
+    "pass_login_gates",
+]
+
+type LoginGate = Callable[[Request, AbstractBaseUser], Awaitable[None]]
+"""A check of a login: return to let it through, raise to refuse it."""
+
+on_login_gate: Final[HookPoint[LoginGate]] = HookPoint(
+    "login gate", arguments=2, awaited=True
+)
+"""Register a gate every login passes (``on_login_gate(gate)`` in ``ready()``)."""
+
+_passed: ContextVar[Any] = ContextVar("login_gates_passed", default=None)
+"""The id of the user whose login passed the gates in this context."""
+
+
+class LoginNotGated(RuntimeError, DomainkitError):
+    """A login was issued without passing the gates: a route forgot them (500)."""
+
+
+async def pass_login_gates(request: Request, user: AbstractBaseUser) -> None:
+    """Run every gate on the login of ``user``; record that it passed.
+
+    Raises:
+        Exception: Whatever the first refusing gate raises.
+    """
+    for hook in on_login_gate:
+        await hook.call(request, user)
+    _passed.set(user.id)
+
+
+@contextmanager
+def gates_passed(user_id: UUID | object) -> Iterator[None]:
+    """Let the login of ``user_id`` through, in the block, with no gate run.
+
+    For code that issues a login on the server side: a sign-in approved
+    from the user's phone, or a test's session. Never wrap a login a
+    request asked for in it: run the gates on that request instead.
+    """
+    token = _passed.set(user_id)
+    try:
+        yield
+    finally:
+        _passed.reset(token)
+
+
+def check_gates_passed(user: AbstractBaseUser) -> None:
+    """Refuse the login of ``user`` if gates exist and it did not pass them.
+
+    Raises:
+        LoginNotGated: A gate is registered and the login skipped them.
+    """
+    if on_login_gate.hooks() and _passed.get() != user.id:
+        raise LoginNotGated(
+            "A login was issued without pass_login_gates(request, user): "
+            "every route that issues a login runs the login gates first."
+        )