Repository navigation
Releases
v0.40.1
webauth 0.40.1
No Breaking change. No migration.
Changes since 0.40.0
- An unavailable rate limiter logs once per outage, without a traceback (#774, PR #775): while the IP rate limiter raises, for example while Redis is down,
IpRateLimitMiddlewarelogs one ERROR line when the outage starts and one INFO line with the count of refused requests when the limiter answers again. Neither line has a traceback, and neither carries the exception message, a key, an address, a path or a header. The state is per process, and a second outage logs again. The 503 withRetry-Afteris unchanged (docs/host-contract.md, STACK-14). - Dependencies: pydantic 2.14.3 (PR #748), ruff 0.17.4 for development (PR #749).
Per app
- hopin (hopin#830): no migration. The log flood during a Redis outage is gone.
- presentator, songmaker and skat: no migration. A log alert that matched the traceback now matches the outage line.
v0.40.0
webauth 0.40.0
No Breaking change. No migration.
Changes since 0.39.1
- The app's own token is reused (#761, PR #765):
OidcRelyingParty.workload_access_tokenreuses the token for each exact scopes tuple until 30 s before itsexpires_in, measured on the monotonic clock. Concurrent calls for one key post one grant and share its answer, whether a token, a refusal or a raised error. Refusals and errors are never kept. An answer without a wholeexpires_inabove the margin is handed out and not kept. The token stays aSecretStrand appears in no repr and no log. Seedocs/host-contract.md, "The app's own token" (WORKLOAD rows). The token exchange still caches nothing (EXCHANGE-05). - The proxy warning quotes no header (#771, PR #773): when the nearest
X-Forwarded-Forentry is not an address, the warning states only the reason and quotes no part of the header, because header contents are never logged.
Per app
- hopin (hopin#838): no migration. Stop expecting one grant per call. If hopin ever preforks, build the relying party in each worker after the fork.
- presentator: no migration. The cache lives on each relying-party instance, so per-test apps stay isolated.
- skat: nothing to do. The logline pilot (skat#604) no longer sees a header value in that warning.
- songmaker: nothing to do.
v0.39.1
What changes in 0.39.1
A patch release of the store contract kit (webauth.store_contract). No Breaking change, no migration.
Per app
- songmaker: the kit now fits
user_sessions.idString(43) andusers.idString(36); adopt 0.39.1 in songmaker#3188. - presentator: drop the test subclass that maps
"member"to"user". - skat and hopin: nothing to do.
Fixed
- #762 (PR #763): the kit creates its test accounts with the role
"user", a role webauth writes (APP-10), never"member". STORECHECK-03 now says a duplicatecreatemay raise any exception. - #764 (PR #766): the kit's session ids have the form sign-in writes (43 characters), and its subjects are uuid strings of 36 characters (STORECHECK-02).
New
webauth.oidc_login.new_session_id(), the one function that mints a session id, used by sign-in and the kit.
v0.39.0
What changes in 0.39.0
0.39.0 prepares every app to run as interchangeable pods over its own Postgres (overnightworks/platform#581). webauth now mints the session id itself. A new contract kit lets each app prove its own store adapter against webauth's ports.
Per app
- songmaker:
createtakessession_id. Dropdefault=_session_tokenindb/models.pyand store the given id; the column does not change. Run the kit in the Postgres store test. - presentator:
SqliteSessionRecordStore.createtakessession_idand stores it; the column does not change. Run the kit in the store test, now and after the move to Postgres. - skat, hopin: build the new Postgres adapter against this
createsignature and prove it with the kit.
Breaking
SessionRecordStore.create(..., *, session_id: str)(#755, PR #756;docs/host-contract.md, MEMSTORE-02, -12, -21, -22, SIGNIN-71).- webauth mints the id at sign-in (
secrets.token_urlsafe(32)), and a store keeps exactly the id it is given. - A store refuses an id it already holds, expired rows included, and never overwrites it.
SingleProcessStoresdoes the same.- Migration: see "Per app"; no store mints an id any more.
- webauth mints the id at sign-in (
New
webauth.store_contract(#757, PR #758;docs/host-contract.md, "Proving a store adapter", STORECHECK-01 to STORECHECK-06).- The host builds a
StoreAdapter(accounts, sessions, transaction, transaction_in_another_process=None)in its own fixture and runs every check ofSTORE_CHECKSagainst it, for example by parametrizing its database test over the tuple. - Each
StoreCheckraisesAssertionErrorwith a reason, whatever the assert setting. It mints its own subjects, usernames and ids, so the checks run in parallel against a shared database; the host removes the rows they leave. - The checks cover
create/load, duplicate ids, unknown and deleted ids,prune_overflow,delete_for_user,touchandreplace_refresh_token, exact subject comparison inget, and writes on a missing account. - One check proves that two
SignInTransactionentries exclude each other across processes. It needstransaction_in_another_process: a picklable callable without arguments, such as a frozen dataclass holding the database location. A single-worker host leaves it unset and skips the checks whosecrosses_processesis true. - It adds no dependency beyond webauth's own and needs no test framework. No check covers
SessionTransaction.
- The host builds a
Not visible to a host
- The host contract states the group check in the token exchange section as the service's alone (#747), and names the platform as owner of the reachability infrastructure (#753).
- The real-browser proof runs against the platform's Keycloak hold (#751).
Full Changelog: v0.38.0...v0.39.0
v0.38.0
What changes in 0.38.0
0.38.0 lets an app act for the caller of its protected resource at another service: it exchanges the token the resource admitted for one the other service accepts (OAuth 2.0 Token Exchange, RFC 8693). Nothing changes for an app that does not use it.
Per app
- hopin (first user): declare the resource with
admits_client_audience=True, and callawait exchanged_access_token(request, scopes=...)inside the admitted resource request. The realm adds the app's client as second audience only after this version runs with the flag on. - skat, songmaker, presentator: nothing.
New
webauth.middleware.exchanged_access_token(connection, *, scopes) -> ExchangedAccess | OidcRefusal(#741, PR #742;docs/host-contract.md, EXCHANGE-01 to EXCHANGE-14).- An
asynccall for a route of the protected resource. It exchanges the token of this very request at the issuer and answersExchangedAccess(access_token: SecretStr, expires_at: int). - The host never sees the admitted token. It is read from the request again, posted only to the issuer of the gate that admitted it, as that gate's client, and never returned, stored or logged.
- It raises
RuntimeErrorwhereresource_personraises, andValueErrorforscopesthat are not a non-empty tuple of scope tokens; nothing is posted then. expires_atis whole wall-clock seconds: the clock before the request plus the issuer'sexpires_in. It is never compared with the admitted token's expiry and can lie after it.- Refusals are closed codes. A 400, 401 or 403 with an error code is
TOKEN_REQUEST_REFUSED; an answer that is not a bearer access token with a wholeexpires_inof at least 1 isTOKEN_ENDPOINT_FAILED(stricter than RFC 8693, which recommendsexpires_in). - Host duties:
scopescome from configuration, never from the request; what an app may obtain for a caller is the issuer's policy and the callee's group check;- a held token is keyed by
resource_person(connection).idof the same request; - at most one exchange in flight per caller, and a refusal is not retried on every request.
- An
ProtectedResource(..., admits_client_audience=False)(#739, PR #740; RESOURCE-18, RESOURCE-56, RESOURCE-84 to RESOURCE-87).- With
True, the resource admits a token whose audiences are itsurlalone or exactly itsurland the app's own client id, in either order, and nothing else. - Such a token stays refused on machine paths, on person paths and on a resource without the flag.
- It exists because the issuer exchanges only a token that names the exchanging client; an app that does not exchange leaves it off.
- With
docs/VISION.mdnames RFC 8693 among the standards webauth follows.
Breaking
None. No migration.
Not visible to a host
- The token endpoint's types and answer readers live in a private module of
webauth.oidc(#737, PR #738); every public import path stays. - The gate and release workflows pin quality v0.11.1 (#735, PR #744).
Full Changelog: v0.37.1...v0.38.0
v0.37.1
What changes in 0.37.1
0.37.1 adds one public name and changes no behaviour: a host can now name every class of webauth's middleware stack without a private import.
Per app
- songmaker: import
PathRefusalMiddlewarefromwebauth.middlewareinstead of the private module. - hopin, skat, presentator: nothing.
New
webauth.middleware.PathRefusalMiddleware(#731, PR #732;docs/host-contract.md, STACK-11).- The class that refuses a path with a control character is exported like the six other classes the installer installs, from the public module
webauth.middleware.path_refusal. - A host can name it in a check of its stack's order.
install_web_auth_middlewarestays the only supported way to add it. - The private module
webauth.middleware._path_refusalis gone; it was never a public name. - No migration.
- The class that refuses a path with a control character is exported like the six other classes the installer installs, from the public module
Full Changelog: v0.37.0...v0.37.1
v0.37.0
What changes in 0.37.0
0.37.0 gives every app a person's language the same way: the account's language from the sign-in, one resolver for "else the browser's", and the app's language named to the issuer. It also closes a path spelling that reached a route past webauth's path rules, and removes one unused parameter. Three changes are Breaking; every host changes its wiring once.
Per app
- Every host:
- pass
ui_language=toinstall_sign_in_routes: a callable that answersresolve_language(...)for the request, orlambda request: Noneto send no language; - build one
AppLanguages(offered, default)and callresolve_language(languages, account_tag=account_language_of_session(...), accept_language=request.headers.get("accept-language"))where the page's language is decided; write only its answer into<html lang>.
- pass
- songmaker, presentator (own session store): add a nullable column of at least 35 characters to the session table, take
account_languageincreateand return it on the record. - hopin, skat (
single_process_stores): no store change. - songmaker:
backchannel_dependenciesis gone; songmaker already stopped passing it. - A host test that sends a path with a control character and expects a route's answer or a 404 now gets 400.
New
webauth.languages(#718, PR #723;docs/host-contract.md, LANGUAGE-01 to LANGUAGE-12).AppLanguages(offered, default)is validated once: each tag in shape,defaultone ofofferedas spelled, no two offered tags equal ignoring case.resolve_language(languages, *, account_tag, accept_language) -> stranswers the first match of the account's tag, then theAccept-Languageranges by descending weight, then the default.- Matching is RFC 4647 Lookup:
de-ATfinds an offeredde;denever finds an offeredde-CH. The answer is the app's own spelling. - A tag that is
None, not in shape or unmatched counts as absent. Weight 0 and*are skipped; a malformed header element is dropped alone. is_language_tagis the one owner of a tag's shape;LogoutPageTextuses it.
webauth.dependencies.account_language_of_session(connection, *, sessions, config) -> str | None(#720, PR #727; LANGUAGE-17 to LANGUAGE-20).- It answers the account's language of the session a request carries, or
Nonewithout a live session. - It only loads. It never renews a session, refuses a request or sets a cookie, so a public page may call it.
- It answers the account's language of the session a request carries, or
Breaking
- The session row carries the account's language (#720, PR #727; LANGUAGE-13 to LANGUAGE-16).
SessionRecordStore.createrequires the keywordaccount_language: str | None;SessionRecordrequires the propertyaccount_language;OidcIdentitygains the required fieldaccount_language.- The callback writes the ID token's
localeclaim when it is a non-empty, printable string of at most 35 characters (MAX_ACCOUNT_LANGUAGE_CHARS), elseNone. Alocaleclaim never refuses a sign-in, and webauth does not judge the tag. - Written at sign-in only. Renewal and refresh-token rotation leave it: a person who changes the account's language sees it after the next sign-in. Sessions from before this release read
None. - Migration: a host with its own session store adds the nullable column, takes the keyword and returns it. A host on
single_process_storeschanges nothing. No host builds anOidcIdentityitself.
- The start route names the app's language to the issuer (#726, PR #728; LANGUAGE-21 to LANGUAGE-27).
install_sign_in_routesrequiresui_language: Callable[[Request], str | None];OidcRelyingParty.begin_loginrequires the keywordui_locales: str | None.- A tag sends
ui_locales=<tag>(OpenID Connect Core, section 3.1.2.1);Nonesends none; a string not in shape raisesValueErrorand nothing goes to the issuer. - Migration: every host passes
ui_language. A host that callsbegin_loginitself passesui_locales=Noneor a tag.
install_sign_in_routesno longer acceptsbackchannel_dependencies(#717, PR #725).- The back-channel logout route is open to anyone who can reach it, and the signed token is its only control; reachability stays the deployment's duty.
- SIGNIN-45, SIGNIN-46 and SIGNIN-48 left the host contract and the later ids of that section moved up by up to three; PR #725 holds the map.
- Migration: a host that passes the argument removes it.
Security
- A path with a control character is refused (#722, PR #724; STACK-08 to STACK-13).
- The standard stack answers an HTTP request whose path carries U+0000 to U+001F or U+007F with 400
{"detail": "Malformed request path"}, ahead of every rule and route. - Before, a path ending in an encoded line feed matched a route while webauth's exact path rules did not know it. Start, callback and logout then spent the default rate budget instead of the sign-in budget and answered without
no-store; the back-channel path lost its exemptions and its body rule. It gave no way to end a session without a signed token. - A refused request spends no rate budget and opens no session lookup. WebSocket handshakes pass untouched.
- No migration.
- The standard stack answers an HTTP request whose path carries U+0000 to U+001F or U+007F with 400
Not visible to a host
Full Changelog: v0.36.0...v0.37.0
v0.36.0
What changes in 0.36.0
0.36.0 gives an async host one call for a signed-in person's groups, fresh from the issuer at each call. Nothing a host uses today changes.
Per app
- hopin: replace
hopin.agent.session_groups.SessionGroupswithwebauth.session_groups.SessionGroups, and delete the copy with its test.- Pass the session transaction where the copy took the bare store:
lambda: nullcontext(sessions). - The class has no
session_id_of; callwebauth.dependencies.session_id_from_request(connection, config)where the session id itself is needed.
- Pass the session transaction where the copy took the bare store:
- skat:
of_session(session_id)is the entry for a plain HTTP route. The store needs nothing beyondreplace_refresh_token. - presentator, songmaker, speech-runtime: nothing to change beyond the pin, and no need to take this release for itself.
New
webauth.session_groups.SessionGroups(relying_party, session_transaction, config)(#711, PR #712;docs/host-contract.md, GROUPS-28 to GROUPS-30).await of_session(session_id)andawait of_connection(connection)answer the groups as afrozenset[str], or theAccessTokenRefusalthatcurrent_groupsanswers, by onecurrent_groupscall on a worker thread.- Fresh at each call. Each call is one refresh grant; nothing is cached.
- No session, no grant. A connection without a session answers
SIGN_IN_AGAINand makes no grant. - A cancelled caller gets no answer, but its grant still stores its rotated refresh token. The cancellation reaches the caller after the grant ends, so a timeout around the call fires only then.
- No lock. Overlapping calls of one session both succeed where the issuer lets a used refresh token be used again, and the last replacement written wins (GROUPS-25 to GROUPS-27). Where an issuer revokes a used refresh token, an overlapping call can answer
SIGN_IN_AGAIN; serialising a session's grants is then the host's.
webauth.admission.app_roletakes anyCollection[str]of group paths, so the reader'sfrozensetpasses to it as it is for a subgroup-aware check (GROUPS-12). A tuple or a list works as before.
Breaking
None. No migration.
Not visible to a host
- A release is dispatched with the version alone and gated before its tag exists, through quality's shared release workflows (#593, PR #713). This release is the first one made that way.
- The private worker helper moved to
webauth/_worker.py.
Full Changelog: v0.35.0...v0.36.0
v0.35.0
What changes in 0.35.0
0.35.0 installs webauth through one standard wiring:
- The host names its sign-in paths once.
- The installer applies every rule those paths imply, and gives every app the same defaults: a sign-in budget, a request budget and a body limit.
It also brings two other changes:
- A route can tell a resource admission from a session admission without an exception.
- A host with a single worker gets webauth's own in-memory stores.
Each host migrates once, through its item.
Per app
- All browser hosts (hopin, skat, presentator, songmaker):
- Pass
sign_in_paths=toinstall_web_auth_middleware. - Drop what the installer now owns: the back-channel's CSRF exemption and body rule, the sign-in paths'
no-storerule, the gate's sign-in public rules, and the rate and body constants that only restated webauth's defaults. - A policy that only adds an exemption or a rule keeps webauth's defaults, so no app copies 600/60 or 4 KiB.
- Pass
- hopin (hopin#652, which also replaces its store fork with
SingleProcessStores):- Keeps its permissions, cache rules and the
/healthexemption (RateLimitPolicy(exempt=…)).
- Keeps its permissions, cache rules and the
- skat (skat#248, likewise with the store fork):
- Keeps its permissions, cache rules, the
/healthexemption and its ownLoginRedirect. - Passes its CSP additions as the wiring's parameters: the call origin's
frame-ancestors, the sign-in pages' script hashes, and the route announcer's style hash derived by its own frontend build.
- Keeps its permissions, cache rules, the
- presentator (presentator#989):
- Its sign-in budget constant leaves.
- It keeps the lobby's 32 KiB body default, the hook's rule, its permissions and its CSP.
- The talk host passes its
talk-filesrule in aRateLimitPolicythat names no default.
- songmaker (songmaker#2921 part 1):
- Drops its four derived references; its sign-in paths spend from the sign-in budget.
- songmaker#2916 uses
is_resource_admission.
- speech-runtime: nothing to change beyond the pin. It calls neither the installer nor a derived property.
- An app still on 0.34.0 may take 0.34.1 and 0.35.0 in one pin.
New
- One standard wiring (#698, PR #704).
- Derived rules.
install_web_auth_middleware(app, sign_in_paths=…, …)puts the derived rules ahead of the host's own (SIGNIN-04 to SIGNIN-08, SIGNIN-44, SIGNIN-68):no-storeon every sign-in path;- the back-channel path's exemption from CSRF and from the rate limit, and its 32 KiB
POSTbody; - with a session gate, the routes' public rules;
- the policy's
sign_inbudget on start, callback and logout.
- The sign-in budget is
RateLimitPolicy.sign_in: 40 requests per 10 minutes per address unless the host sets another (SIGNIN-69). - Field defaults. The default budget is 600 requests per 60 seconds and the default body limit 4 KiB. These are the policies' own field defaults, and the installer applies them when the host passes no policy (STACK-05, STACK-06).
- Rate limit details. A path in the host's
RateLimitPolicy.exemptspends no budget, a sign-in path included (SIGNIN-72). The rate limit counts every method,HEADandOPTIONSincluded (SIGNIN-73). - Permissions. The default permissions policy also turns off
display-capture(STACK-07).
- Derived rules.
webauth.middleware.is_resource_admission(connection) -> bool(#693, PR #695). It tells a route whether the resource admitted this very request as its capped person (RESOURCE-81 to RESOURCE-83).webauth.single_process_stores.SingleProcessStores(audit=…)(#697, PR #699). It givesaccounts,sessionsandtransactionfor a host with one worker (MEMSTORE-01 to MEMSTORE-20). Thedelete_for_userdocstring of the port now says a store may also remove the account.KEY_SET_REFRESH_WAIT_SECONDScame with 0.34.1.
Breaking
All from #698:
install_web_auth_middlewarerequiressign_in_paths.- The derived properties of
SignInPathsare gone, with no alias:public_rules,browser_paths,backchannel,backchannel_body_size_ruleandcache_control_rule.login_redirectstays. - A
RateLimitPolicywhose default or one of its rules carries the sign-in budget's name ("sign-in"unless renamed) raisesValueError(SIGNIN-70). - When the host leaves out its own default, a rule or a renamed
sign_inbudget named"default"raisesValueErrortoo (STACK-05).
Migration: as listed per app above. No data step.
Not visible to a host
- CI jobs stop after 10 minutes, the tests run on parallel workers, and every run on main keeps a concurrency group of its own (#700, PRs #701 and #702).
- Dependabot moved the locked anyio to 4.16.0 (#703). The floor
anyio>=4.0,<5stays. - A test proves both rate-limit windows (#706, PR #707).
- The test arrangement module is split (#708, PR #709).
Full Changelog: v0.34.1...v0.35.0
v0.34.1
What changes in 0.34.1
0.34.1 fixes a defect that sometimes refused a valid token right after a restart, or when the key set expired.
Per app
- hopin, presentator, songmaker, speech-runtime and skat: nothing to change beyond the pin. Each of them verifies tokens through this code, so each one gets the fix.
- skat: this release ends the key-set race that turned skat's main CI red.
Fixed
- A token check waits for a key-set refresh already under way (#690, PR #691).
- Suppose no current key set exists, the last refresh attempt did not fail, and another request is refreshing. A verification then waits for that refresh, at most
KEY_SET_REFRESH_WAIT_SECONDS(10), and uses the key set it left (CALLER-34). - So a valid token is no longer refused with
key-set-unavailableduring a cold start or when the key set expires. KEY_SET_REFRESH_WAIT_SECONDSis a new name inwebauth.jwt_verification.
- Suppose no current key set exists, the last refresh attempt did not fail, and another request is refreshing. A verification then waits for that refresh, at most
Breaking: none. Migration: none.
Not visible to a host
- The list of code built ahead of its caller is gone (#687).
AGENTS.mdtakes the fleet's shape (#688).
Full Changelog: v0.34.0...v0.34.1