ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
test(auth): ratchet the JWT-only population and record the A decision
Juan Deniseb83d332e774
diff --git a/backend/tests/JWT_ONLY_CEILING b/backend/tests/JWT_ONLY_CEILINGnew file mode 100644index 00000000..695668dd--- /dev/null+++ b/backend/tests/JWT_ONLY_CEILING@@ -0,0 +1 @@+605diff --git a/backend/tests/jwt_only_census.py b/backend/tests/jwt_only_census.pynew file mode 100644index 00000000..a6561234--- /dev/null+++ b/backend/tests/jwt_only_census.py@@ -0,0 +1,116 @@+"""Count routes still authenticated by bare ``@jwt_required()`` (plan 76, A).++``auth_required()`` (app/middleware/rbac.py) is milestone A's door: it accepts+a JWT *or* an ``X-API-Key``, resolving both through the same identity path.+``@jwt_required()`` accepts only the JWT.++That difference is why this census exists and why it is NOT a migration+countdown to zero. Converting a route from ``@jwt_required()`` to+``auth_required()`` **grants API-key callers access to that route** — an+expansion of the authenticated surface, not a refactor. The recorded decision+(2026-08-19, closing the plan's open question) is:++ JWT-only is the deliberate default. A route becomes API-key capable+ one at a time, when an API-key use case exists for it, in a commit+ that says so — never as a mechanical sweep.++So the ceiling is an adoption ratchet in one direction only: the population+may shrink as routes are deliberately converted, and may not grow — a NEW+route must pick a policy decorator (``auth_required()`` or a role decorator),+not bare ``@jwt_required()``. The identity-door ratchet's third assertion+(tests/test_identity_door_ratchet.py) is what makes each conversion safe: it+fails the moment a route becomes API-key capable while still resolving its+caller from the JWT.++Counting is AST-based over ``app/api``: a decorator ``jwt_required`` (called+or bare) on any function.++Usage (from ``backend/``)::++ python tests/jwt_only_census.py # print the count + report+ python tests/jwt_only_census.py --update # write the count as the ceiling+"""++import ast+import os+import sys++HERE = os.path.dirname(os.path.abspath(__file__))+BACKEND = os.path.dirname(HERE)+API_DIR = os.path.join(BACKEND, 'app', 'api')+CEILING_FILE = os.path.join(HERE, 'JWT_ONLY_CEILING')++SKIP_DIRS = {'__pycache__'}+++def _rel(path):+ return os.path.relpath(path, BACKEND).replace(os.sep, '/')+++def _decorator_name(dec):+ while isinstance(dec, ast.Call):+ dec = dec.func+ return getattr(dec, 'attr', getattr(dec, 'id', ''))+++def count_file(path):+ """Return [(lineno, function_name)] of jwt_required-decorated functions."""+ try:+ tree = ast.parse(open(path, encoding='utf-8').read())+ except (SyntaxError, UnicodeDecodeError):+ return []+ found = []+ for node in ast.walk(tree):+ if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):+ continue+ for dec in node.decorator_list:+ if _decorator_name(dec) == 'jwt_required':+ found.append((node.lineno, node.name))+ break+ return sorted(found)+++def census():+ found = {}+ for dirpath, dirnames, filenames in os.walk(API_DIR):+ dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]+ for name in sorted(filenames):+ if not name.endswith('.py'):+ continue+ path = os.path.join(dirpath, name)+ hits = count_file(path)+ if hits:+ found[_rel(path)] = hits+ return found+++def total(found=None):+ if found is None:+ found = census()+ return sum(len(v) for v in found.values())+++def read_ceiling():+ with open(CEILING_FILE, encoding='utf-8') as f:+ return int(f.read().strip())+++def _write_ceiling(value):+ with open(CEILING_FILE, 'w', encoding='utf-8') as f:+ f.write('%d\n' % value)+++if __name__ == '__main__':+ found = census()+ count = total(found)+ for rel in sorted(found, key=lambda p: (-len(found[p]), p))[:15]:+ print('%-40s %d' % (rel, len(found[rel])))+ print('\ntotal: %d' % count)+ if '--update' in sys.argv:+ _write_ceiling(count)+ print('ceiling updated to %d' % count)+ else:+ try:+ print('ceiling: %d' % read_ceiling())+ except FileNotFoundError:+ print('no ceiling file yet; run with --update')diff --git a/backend/tests/test_jwt_only_ratchet.py b/backend/tests/test_jwt_only_ratchet.pynew file mode 100644index 00000000..2f02aa4d--- /dev/null+++ b/backend/tests/test_jwt_only_ratchet.py@@ -0,0 +1,82 @@+"""The JWT-only adoption ratchet (plan 76, milestone A closure).++This ratchet records a DECISION, not a debt: bare ``@jwt_required()`` routes+are JWT-only on purpose, because converting one to ``auth_required()`` grants+API-key access — a per-route policy call, never a sweep. See the module+docstring in ``jwt_only_census.py`` for the recorded decision.++What the ceiling enforces is the two directions that must not happen:++ * the population must not GROW — a new route picks a policy decorator;+ * a conversion must not be silent — shrinking the count requires the+ committer to refresh the ceiling in the same commit, which is exactly+ the "a commit that says so" the decision demands.+"""++from jwt_only_census import census, count_file, read_ceiling, total+++def test_the_count_is_at_or_below_the_ceiling():+ found = census()+ count = total(found)+ ceiling = read_ceiling()+ worst = sorted(found, key=lambda p: -len(found[p]))[:5]+ assert count <= ceiling, (+ f'{count} routes authenticate with bare @jwt_required(), ceiling is '+ f'{ceiling}.\n'+ f'New routes must use a policy decorator (auth_required() or a role '+ f'decorator), not bare @jwt_required().\n'+ f'Heaviest files: ' + ', '.join(f'{p} ({len(found[p])})' for p in worst)+ )+++def test_the_ceiling_is_not_stale():+ """A slack ceiling would let JWT-only routes creep back in unnoticed."""+ count, ceiling = total(), read_ceiling()+ assert ceiling - count <= 10, (+ f'ceiling {ceiling} is {ceiling - count} above the actual {count}; '+ f'run `python tests/jwt_only_census.py --update`'+ )+++class TestTheCensusCountsTheRightThings:+ """A miscounting ratchet is worse than none: it reads green either way."""++ def _count(self, tmp_path, source):+ path = tmp_path / 'sample.py'+ path.write_text(source, encoding='utf-8')+ return len(count_file(str(path)))++ def test_counts_the_called_decorator(self, tmp_path):+ assert self._count(tmp_path, (+ "@bp.route('/x')\n"+ '@jwt_required()\n'+ 'def handler():\n'+ ' pass\n'+ )) == 1++ def test_counts_the_bare_decorator(self, tmp_path):+ assert self._count(tmp_path, (+ '@jwt_required\n'+ 'def handler():\n'+ ' pass\n'+ )) == 1++ def test_does_not_count_policy_decorators(self, tmp_path):+ assert self._count(tmp_path, (+ "@bp.route('/x')\n"+ '@auth_required()\n'+ 'def a():\n'+ ' pass\n'+ '\n'+ '@admin_required\n'+ 'def b():\n'+ ' pass\n'+ )) == 0++ def test_does_not_count_a_call_inside_the_body(self, tmp_path):+ """Only the decorator position is an authentication choice."""+ assert self._count(tmp_path, (+ 'def handler():\n'+ ' verify = jwt_required()\n'+ )) == 0