Skip to content

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.

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_CEILING
new file mode 100644
index 00000000..695668dd
--- /dev/null
+++ b/backend/tests/JWT_ONLY_CEILING
@@ -0,0 +1 @@
+605
diff --git a/backend/tests/jwt_only_census.py b/backend/tests/jwt_only_census.py
new file mode 100644
index 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.py
new file mode 100644
index 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