Repository navigation
Refactor/composable features - #305
Merged
Merged
Conversation
…ill catch what is left behind
…p it out of the logs
…ssion to the admin
…n gate from settings
…top refusing good keys
…no slower when the address exists
…the configured one
…estinations and usage user agents
…e removal drill never regenerates
…tring as a second module docstring
…ks still hold when it lands
…er waits on a mail server
…test that they stay drawn
…pose file, and seed with a password the policy accepts
… env file a container never has
… names the environment it is checked for
… both credentials
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Composable features
The boilerplate said "delete the parts you don't want", which was true of directories and false of imports.
modules/rate_limitimported the tier models, the API throttle readtier_idoff the user row, the authorization checks imported the role tables,create_applicationnamed every router by hand, the seeders ran whether or not their tables existed, and the test fixtures assumed every account had a tier. Delete one directory and four others broke, so nobody deleted anything, and the parts nobody deletes are the parts nobody reads.This branch makes nine features removable, each of them leaving with its routes, models, settings, admin views, seeders, fixtures and tests: accounts, rbac, tiers, tier_limits, ratelimit, api_keys, admin, cache and taskiq. The cross-feature imports are gone, replaced by a composition root. The auth stack moves to crudauth 0.8.2, which takes back the session routes, the session store and the lockout counters that had been rewritten here. Roles and API keys now share the permission registry as their only vocabulary, so a scoped credential is weaker than its owner rather than equal to it.
Three review rounds went over the result and found a privilege escalation this branch had introduced, two races that corrupted state instead of failing, a family of
500s that should have been422since the beginning, and recovery routes whose timing told a caller which addresses had accounts. All of that is fixed here, each fix in its own commit, with the failure reproduced first and the new guard mutated afterwards to prove its test fails without it. The full gate runs before anything lands: lint, types, the suite forwards and in reversed collection order, the CLI, and the removal drill. A security pass closes the branch: the two reports open against the project were audited line by line, and most of what they describe was already answered by the work above, so what was left, the admin panel's defaults, is fixed here, and every dependency carrying a published advisory is at a patched release.A feature is a set of paths and a few contributions
The composition root is a rule about direction: a feature contributes to extension points it does not own, and nothing imports it back. The shapes it contributes through live in
infrastructure/composition.pyand are deliberately thin, aRouterMount, aLifecycle, aPermissionSource, aRateLimitResolver, aTierDeleteGuardandTierDeleteRelease, aReadinessCheckin one of two groups, model and schema extensions for the user row, and an installer callable. Each is a function type or a frozen dataclass, because the moment a contribution needs a base class, the feature on the other side has to import it.What a project selected is listed in
src/wiring/:app.py,settings.py,hooks.py,models.py,admin.py,email.py,cache.py,transports.py,tasks.pyandtables.py, withbackend/scripts/seeders.pyandbackend/tests/wiring.pydoing the same for seeders and fixtures. Those files are the only place that knows the whole set, since a feature owns its settings class, its error-to-status mapping, its fixtures and its permission declarations. Composable Features is the guide.Some code belongs to two features at once: an API key scoped to an RBAC permission, a tier column on an admin form, a test that needs both. None of that is a contribution from one feature to another, it is code that makes no sense without both, so it lives in a path that leaves with either side. The manifest calls those
combination_paths, and the two tests and one admin assertion that moved into them were each found by a preset failing rather than by someone reading.Why the wiring is generated and then compared
Hand-written wiring and a generator that claims to reproduce it will drift, on the day somebody edits one of them. So
tools/removal_drill.pyholds the generator, andtests/unit/test_removal_drill.pyregenerates every wiring module for the features this repository carries and compares the result against the committed file by AST, ignoring docstrings, comments and formatting. A contribution added by hand and not to the generator fails there, which has already caught the two drifting apart.The same comparison decides where a reader puts code of their own. The Logfire recipe in Observability wires its installer in the composition root,
src/interfaces/main.py, rather than insrc/wiring/app.py, because an earlier version of that recipe edited the generated file and left anyone who followed the guide with a failing test.The drill is the test of the architecture
python tools/removal_drill.pycopies the repository to a scratch directory once per preset, deletes the paths of every unselected feature, regenerates the wiring for what is left, and then runs six checks over it: the app imports, every module imports,ruff check src tests,mypy src scripts migrations tests,pytest tests, and an Alembic baseline applied to an empty database. Nine presets run as a CI matrix, fromcore-onlywith no features at all up toeverything.The baseline is in there because it is the only check that makes a removal visible. A feature's tables leave with it, and the schema the baseline creates is compared against what the models declare, so dropping the
key_permissionstable showed up as one table and five indexes fewer in exactly the place it should have. A preset carrying fewer features skips the tests whose subject it no longer has, which is the drill's own build tests for absent features and a throttle comparison that needs two throttled routes to compare budgets. On the full tree nothing is skipped.Why a copy of the repository and not a setting
A feature flag would prove the code runs with a feature switched off, which is a weaker claim than the one being made. The drill deletes paths instead, so a stray import of a removed module is an
ImportErrorin the copy rather than a branch nobody took. That costs minutes per preset, and it is the version of the check that means something.Auth: giving the work back to the library
The pin moves from
crudauth[all]>=0.7.1,<0.8.0to>=0.8.2,<0.9.0, and what the library now does better is deleted here: the session routes written in this repository, the logout path, the session store and the lockout counters. crudauth's session-management router replaces them and brings a device list and per-device sign-out with it. SettingSESSION_BACKEND=databaseandRATE_LIMITER_BACKEND=databasekeeps sessions and lockout counters in the project's own database, so several workers share them without a Redis.Two of the choices there read as omissions. The first is
set-password, which this project does not mount: it would let anyone holding a session put a password on a provider-only account, and that is a takeover whenever a session is borrowed. Such an account sets its first password through the reset link, which proves the address first.The second is the sign-out. crudauth 0.8 looks a session up under an HMAC of its id keyed with
SECRET_KEY, so sessions written by 0.7 sit under the raw id and are no longer found, and everyone signs in again after the deploy. ASECRET_KEYrotation now does the same thing, which the admin-panel guide states plainly instead of recommending a rotation as the way to clear panel sessions.The bump was priced before the pin changed: every symbol and method this project touches was diffed between the installed 0.7.5 and the 0.8.2 source, and the suite was then run against 0.8.2 by
PYTHONPATHshadowing. Two tests failed, both of them the re-login revocation above. The test written for it was run against 0.7.5 in a scratch target afterwards, to watch it fail there, since a test that passes on both versions proves nothing about either.One vocabulary for authorisation
Permissions are a registry that any module declares into without importing rbac, and
GET /api/v1/permissionslists what the project has while/permissions/melists what the caller holds. Roles and API key scopes carry the same registry names, and there is no second vocabulary for either. The one that used to exist was a table ofkey_permissionsrows keyed by words likeconversations,credits,user_profileand*, describing access that no route could check.The role API runs on one rule: nobody hands out what they do not hold.
can_delegate_permissionsandcan_assign_rolecompare against the caller's effective permissions, resolved once per request and narrowed to the credential's scope, and deleting a role or emptying it is held to the same rule for every live holder, because taking a permission away from an account the caller cannot reach is the same escalation as giving one.A key is never a superuser, and the flag is cancelled where the principal is built: the transport returns a principal without it and records the owner's flag in the credential's metadata, where only the permission narrowing reads it. The first version cancelled the flag at each gate, and review found two gates it had missed,
role/delegation.pyanduser/service.py, the first of which let a superuser's key scoped torole.assignassign any role to any account. Cancelling it once means no consumer has to remember. The same reasoning covers the owner's own resources: a key scoped for reading cannot rename the account behind it, because ownership on its own is not a licence.What an API key is, and what it may do
A key is
secrets.token_urlsafe(48), which is 384 bits of server-generated randomness, so there is nothing to guess and a work factor buys nothing. It costs something, though. The old scrypt storage made every key request pay a derivation, and sincekey_prefixappears in listings, anybody holding a prefix could make the server pay it on junk requests. Storage issha256$<digest>now, found by one indexed lookup, while keys stored the old way still authenticate by prefix and the old verification and are rewritten on first use. A script names the ones that never moved and revokes them on request. A scanner may flag SHA-256 here as weak password hashing, and for this column that reading is wrong, which the guide explains.Key management belongs to a session. Minting, reading, rescoping and revoking all refuse a key, so a key cannot mint another, widen itself, or revoke the one an operator would use to stop it. Minting also needs a verified address, because an unverified address may belong to somebody else, and that is what lets an attacker register under a victim's address, mint a key, and keep API access after the victim claims the account through a provider. The test holding all of this reads the key routes off the app rather than from a list, so a route added later is covered without anyone remembering.
Usage limits are counted at authentication, per key id, on the limiter behind the login lockout, which means they cover every route the key can reach whether or not that route is throttled. Windows are counted shortest first, so a request the minute window refuses keeps its hour and day budgets, and counting fails open, because a limiter nobody can reach should let the request through rather than take the API down with it. A key held at its limit records one refused request per window instead of one per request, so a client hammering a full window costs the limiter and nothing else.
Every request a key authenticates writes one usage row as a background task after the response, carrying the path, the method, the status the client actually got, the duration, the address and the user agent. Rows are kept for
KEY_USAGE_RETENTION_DAYS, pruned by a scheduled task where there is a worker and byscripts/prune_key_usage.pywhere there is not.What a route answers
Much of the review was not about features at all, but about answers. Input that used to reach Postgres and come back a
500answers422now: page numbers and ids past theIntegerrange, expiries that cannot be expressed in UTC, a NUL character anywhere in a body or a query, text no column can hold on the routes crudauth owns, and a rate limit'spath, which is validated as the route template it has to match. A signup that loses a race for an address or a username answers409, and the index that refused the row decides which of the two it was, rather than a pre-check. A key whose stored row no schema can read answers401instead of a500on every request it makes.Recovery routes answer the same way and in the same time. They send only where the address has an account, and the sender used to be awaited in the request, so one path published to the broker while the other did nothing, and a caller could time the difference to learn who is registered. Against a broker that was down the gap was the whole
BROKER_CONNECT_SECONDS, with the SMTP fallback on top of it. The message now goes to a task of its own and the shutdown drains what was handed over, so both paths answer in the time it takes to make a task.That handover started inside the taskiq feature, which left a project without a worker carrying the very oracle the fix was for. It is core now, in
infrastructure/handover.py, the sender such a project is wired to is wrapped inHandingOverSender, and a lifecycle drains it at shutdown. The two drain budgets differ by what each can legitimately take, one delivery to a mail server here, the queue leg on top of it with a worker.A signup answers the same way whether the address was free or taken, creating nothing in the second case and telling the account that holds the address that somebody tried to sign up with it. A message waiting in the queue is sealed, so a verification or reset link cannot be read out of Redis or RabbitMQ, or out of a backup of either. And a confirmed email change ends every session the account had, since the address is what recovers an account.
Writes that race
Two findings in the last round were worse than the
500s that led to them.POST /roles/{id}/users/{user}looked for an assignment and then inserted it, so two at once answered201and500.PUT /roles/{id}/permissionswas quieter and worse: each replacement deletes what the role carries and inserts its own, neither saw the other, and the role came out carrying the permissions of both requests, one set of them from a caller who had asked for the other. That is not a failed request, it is a role nobody configured.Every write path takes the role's row first with
SELECT … FOR UPDATE, so writes to one role queue, and that turned out not to be enough on its own. The checks that decide whether a caller may reach an account read what that account holds, and a superuser handing it a stronger role landed between the check and the write, leaving the caller having changed the roles of an account stronger than themselves. So the account's row is taken as well, withFOR NO KEY UPDATE, which blocks another grant write, a delete and a promotion while leaving alone theFOR KEY SHAREan unrelated foreign key takes, so an API key or a usage row for that account never waits on a role change. Where a write changes every holder's grants the holders are takenFOR SHARE, which lets two of those run at once while an assignment to one of them waits, and a role's row is always taken before an account's, so two orders never meet.Rate limits had the same shape without the lock. Nothing stopped a second row for one
tier_idandpath, and the limit a caller got was whichever row the lookup read first, so two rows saying10and1000made the throttle a toss-up that could land differently after a restart. A partial unique index over(tier_id, path), covering the rows a soft delete has not taken out, refuses the second one;PATCHanswers409when the new path is one the tier already limits; and a rule for a tier deleted mid-write answers404for the tier instead of a conflict with another rule, because the constraint that refused the row is read off the driver's own error.What the tests for those had to look like
A race whose every outcome is legal cannot be caught by asserting a status, since two concurrent assignments answering
201and201is the same pair whether the writes queued or not. These tests assert on waiting instead: the competing write starts as a task, and the request holding the lock checks that it has not finished. The writes that must not wait are awaited under a timeout, so a write that is genuinely blocked fails the test rather than hanging the suite.asyncio.gatheron its own never reproduced any of this, because lockstep scheduling misses the window, so the interleavings are forced with a barrier around the real per-request permission lookup.Operations
Readiness answers for what a request needs.
GET /health/readyis503while the database, its schema, the lockout limiter or the session store is unreachable, and stays200for the cache and the task broker, which no request waits on. Probes run together, each under its own two-second timeout, deduplicated per server, and the report is reused for a couple of seconds so that a flood of probes cannot take the connection pool from real requests. Two checks that reach one host as different users are told apart, so a cache pointed at the limiter's host with the wrong password is reported down rather than ready by mirroring the limiter's answer.The admin panel sits inside the app's security rather than beside it, and is off until a project asks for it:
ADMIN_ENABLEDunset leaves/adminunmounted, and so does either credential being empty, since such a panel could only ever serve a login form. Its login failures used to be counted where the public login's lockout could not see them, and per address, so one password could be tried from one address after another; they feed the shared lockout againstadmin-panel:<address>now, and every refusal is recorded. The panel refuses cross-origin writes, ends a session on aPOSTonly, and binds a session to the credentials that made it, with the fingerprint it binds by derived under a work factor once, as the panel is built, rather than per request. Its CSV export writes formula-like cells as text, and the suite fails any exporting view that doesn't.Tracing ships as a recipe rather than as a feature. The project emits structured logs, a support id per failed request, readiness per dependency and a usage row per key request, and Observability shows how to put Logfire or a plain OTLP collector in front of that material without exporting a session cookie or a bound parameter. It also says what a project that wants observability to be removable would have to add to the manifest instead.
How each change was proved
The loop is the same every time: reproduce the failure as a test that fails for the stated reason, make the smallest change that answers it, then mutate the new guard and run its test again to watch it fail without the guard.
A mutation that leaves the suite green means the guard is untested, and three times it meant the test was asserting something else: an API key refusal's message that could never fail, a role path's account id the sweep had never covered, and a lockout read under the identifier as typed rather than as the limiter keys it. Two of my own tests were rewritten after their mutations survived, one that asserted a script appeared somewhere on a documentation page rather than in each tree that draws it, and one that proved a delivery was not waited on by hanging when it was. Two mutations are left green on purpose and the commits say so: a bound's number can be changed in the one place every schema, column and test reads it from, and a lock stricter than it needs to be still passes.
The documentation is held to the code by tests rather than by review. Every
pythonblock's project imports have to resolve, the documented baseline command has to name the database it runs against, no documented block may bring a stack up frombackend/, both script trees have to draw every runnable script, and the tracing recipe has to wire itself outside the generated wiring.Verification
The architecture
core-onlythrougheverythingsrc/interfaces/main.pysurvives a regeneration unchanged, which is what the tracing recipe relies onAuthorisation
user.updatecan/api-keys/route refuses a key and answers a session, read off the app rather than from a listRaces
201and201, and two replacements leave the role carrying one set of permissions rather than bothAnswers
201with nothing created and notifies the owner; a taken username still answers409201Operations
503for an unreachable database, schema, limiter or session store, and200for a cache or broker that is downpre-commit run --all-filespassesA fresh clone
uv sync,bp deploy generate localanddocker compose upbring up the API, the worker, the scheduler, Postgres and Redis, with the schema built and the admin seeded429carriesRetry-After, a production environment refuses the development defaults, and the generated baseline carriesuq_rate_limits_tier_pathwith itsWHERE, thevarchar(2048)and bothtoken_versioncolumnsThe run found five things the suite could not see, each fixed in this branch. The documented Docker quickstart had no generate step and ran compose from
backend/, where the compose file no longer is..env.exampleshipped anADMIN_PASSWORDthe password policy refuses, so the first seed half-succeeded and said little about why. Alembic inside the container found no configuration, because the stages work from/app/srcandalembic.inisits at/app. Every container command opened with a warning about an environment file a container never has. Andbp env validateaudited for production while its findings named the environment the configuration was read in. The pages a reader follows are swept by a test now, as the samples and the script trees already were.A second run, on a fresh clone of the upgraded branch, found one more. The generated compose mapped the database credentials through
${POSTGRES_PASSWORD:-postgres}in thepostgresservice'senvironmentblock, which compose fills from the shell rather than from theenv_filebeside it, and which overrides that file: a password set inbackend/.envwas replaced inside the container by the literalpostgres, so the database initialised with the well-known default and the API could not connect with the password it had been given. All three modes carried it. The block is gone, sinceenv_filealready supplies the names the image reads, and the readiness probe resolves the user inside the container now. Both are pinned by a test over the rendered compose for each mode.Dependencies
One pin moved for the work itself:
crudauth[all]>=0.8.2,<0.9.0, up from>=0.7.1,<0.8.0.The rest is security. Every dependency with a published advisory is at a patched release in the lock, which is what the image installs from: aiohttp, anyio, certifi, Mako, multidict, pydantic-settings, PyJWT, python-multipart, sqladmin, starlette and urllib3. Two floors this project declares moved with them,
sqladmin>=0.28.0andpydantic-settings>=2.14.2, andanyio>=4.15.1andstarlette>=1.3.1are declared for the first time, because the task groups, middleware, requests and responses the code imports come from those two rather than through FastAPI. sqladmin takes arequestinexport_dataas of 0.28, which the CSV export mixin accepts and passes on, and which is where the floor is set: on 0.27 that call would raiseTypeError.Breaking changes
The changelog carries every one of them with its migration step. These are the ones a caller or a client notices.
usage_limitsmay name only the three windows the limiter counts,key_permissionsis gone, andsrc/modules/api_keys/__init__.pyexports nothing.403until the account's address is verified.POST /api/v1/users/answers201with a fixed message whether the address was free or taken, and no longer returns the created profile. A client readingresponse.json()["id"]has to read the account back after signing in.POST /auth/refresh-csrfis nowPOST /auth/csrf/refresh, andlogout-allanswers{"detail", "revoked"}where it answered{"message", "terminated_count"}.PATCH /users/{username}no longer takesemail. An account moves its address through the confirmed flow, which ends every session it had.SECRET_KEYrotation from now on.items_per_pageabove 100 answers422, as do out-of-range ids, pages and expiries, and text no column can hold.redirect_toare held to 2048 characters, and a usage row keeps the first 512 of a user agent.CORS_ORIGINSallows nothing, an unknownSESSION_BACKENDis refused at startup, andCREATE_TABLES_ON_STARTUPis refused in production.ADMIN_ENABLEDdefaults tofalse, and a panel whoseADMIN_USERNAMEorADMIN_PASSWORDis empty is not mounted, since it could only ever serve a login form.infrastructure/auth/deps.py.What a deployment has to do, in order
bp deploy generate local|prod|nginx, before anything else runs through it. The one you have takes the database credentials from the shell rather than frombackend/.env, so a stack that worked was running Postgres on the default password; if the volume was initialised with it, recreate the volume and restore, or change the password inside the database to the onebackend/.envcarries.scripts/cleanup_api_key_json.pyand rescope the keys it reports.profile_image_urllonger than 2048. Migrations has the query for each, next to the one for addresses that differ only in case.migrateprofile. It addsuser.token_versionandapi_keys.owner_token_version, both defaulting to0, the(tier_id, path)index and the length onprofile_image_url, and it dropskey_permissions.CORS_ORIGINSexplicitly.KEY_USAGE_RETENTION_DAYSand schedule the prune: the taskiq task where there is a worker,scripts/prune_key_usage.pyfrom cron where there is not.ADMIN_ENABLED=true, withADMIN_USERNAMEandADMIN_PASSWORD, if you were reaching/adminwithout setting it. Unset, it is off now, and the panel is not mounted without both credentials.