Stop counting optional authentication as protection

[EdwardPham1615]

Candidate addition #5 — the first of the seven, taken first because it is a security-audit helper that reports success incorrectly.

assert_routes_protected passed routes that anyone can call. A route depending on Auth.optional_user lets an anonymous caller through, but it declared the same HTTPBearer scheme as Auth.current_user — so the generated document was byte-identical and the audit could not tell an open endpoint from a guarded one. Reproduced before changing anything: two routes, one of each, both security=[{'HTTPBearer': []}], and the check silent.

The fix

Auth.optional_user declares its own scheme name, exported as py_common.security.OPTIONAL_AUTH_SCHEME:

/public/card   security=[{'OptionalBearer': []}]
/api/v1/me     security=[{'HTTPBearer':     []}]

Both dependencies still read the same Authorization header and admit exactly the same callers. The scheme is the only place the document can distinguish must be authenticated from may be.

Two recorded alternatives, tried and dropped

The recorded proposal offered either marking the route in OpenAPI or teaching the checker to read {} as public. I tried both:

• openapi_extra={"security": [{}, ...]} appends rather than replaces — it produced [{'HTTPBearer': []}, {}, {'HTTPBearer': []}]. Readable by the checker, but messy in the spec and the burden lands at every call site.
• Teaching the checker to read {} carries the same call-site cost.

A distinct scheme name needs nothing from the consumer and makes the document more informative.

The combination that is still protected

Optional auth on a protected_router stays protected — the router's guard demands a token, and the check asks whether any declared requirement does, not which came last:

/api/v1/card   security=[{'HTTPBearer': []}, {'OptionalBearer': []}]   → protected

My first test app got this wrong: it put the "public" route on a protected router, and the assertion failed because the route genuinely was protected. The distinction is now asserted directly, since it is the part most likely to be broken by a later simplification.

One thing about the layering

testing/routes.py spells the scheme name out instead of importing it from py_common.security. That import would pull PyJWT into a module needing only the http extra — the failure make extras-check exists to catch, and one this branch's first draft walked straight into before #61 widened the check to cover py_common.testing.routes. A test pins the two copies equal.

Consumer impact

This can newly fail a consumer's test suite, which is the point: optional-auth routes now have to appear in public_paths/public_prefixes. The OpenAPI document also gains an OptionalBearer scheme, visible as a second entry in Swagger's Authorize dialog.

Verification

403 passed (from 399), coverage 92.23%, make extras-check green on all twelve pairs.

Mutation-checked three ways, each turning tests red:

mutation	result
revert optional_user to the shared bearer	2 tests fail
remove the checker's optional-scheme branch	1 test fails
desynchronise the two copies of the constant	2 tests fail

Next

Six candidates remain, in the planned order: #3 (sqlalchemy ceiling + a scheduled fresh-resolve job), #6 (adopt uvicorn's loggers — not uvicorn.access, which would duplicate the access log), #2, #4, #1, #7. Then release 0.3.0.