Skip to content

See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.

fix(health): recognize validated FastAPI Header token guards

Bl0ck15455972638e74c
diff --git a/skills/floorplan/scripts/lib/health.mjs b/skills/floorplan/scripts/lib/health.mjs
index a5cb39e..2c2cee0 100644
--- a/skills/floorplan/scripts/lib/health.mjs
+++ b/skills/floorplan/scripts/lib/health.mjs
@@ -205,6 +205,15 @@ const isDbDep = (name) => DB_DEPENDENCY.test(snake(name));
const isGuardDep = (name) => isGuardName(name) && !isDbDep(name);
// A handler body that inspects the caller itself.
const INLINE_CHECK = /request\.headers(?:\.get)?\(?\s*\[?\s*['"](authorization|x-api-key|x-[\w-]*(token|key|secret|signature)[\w-]*)['"]|req\.headers(?:\.|\[\s*['"])(authorization|x-api-key)|\b(verify|check|require|validate|authenticate|authorize)_?\w*(auth|token|session|user|key|signature|webhook|hmac|jwt|device|staff|admin|permission|role|request|caller)\w*\s*\(|\bcurrent_user\b|get_jwt_identity|verify_jwt_in_request|compare_digest|abort\(\s*40[13]\b|,\s*40[13]\s*\)?\s*$|status(?:Code)?\s*[:=(]\s*40[13]\b|\.status\(\s*40[13]\s*\)|req\.user\b|req\.session\.user|req\.auth\b|jwt\.verify|jwtVerify|getServerSession|auth\(\)|currentUser\(|getAuth\(|auth\.getUser|getSession\(|verifyIdToken|getToken\(/m;
+// A Header parameter alone is NOT authentication. Count it only when the
+// handler checks that token and rejects a bad value with HTTP 401/403.
+function pyValidatedHeader(sig, body) {
+ const names = [...sig.matchAll(/\b([A-Za-z_]\w*(?:token|key|signature)\w*)\s*:\s*[^,\n]*=\s*Header\s*\(/g)]
+ .map((m) => m[1]);
+ if (!names.length || !/raise\s+HTTPException\s*\(\s*status_code\s*=\s*40[13]\b/.test(body)) return false;
+ return names.some((name) => new RegExp('\\bif\\s+(?:not\\s+)?' + name + '\\b').test(body));
+}
+
const FIREBASE_CHECK = /\b\w+\.auth\b(?!\s*\()|HttpsError\(\s*["'](unauthenticated|permission-denied)["']|enforceAppCheck\s*:\s*true|\b\w+\.app\b\s*(==|!=|===|!==)\s*(undefined|null)|!\s*\w+\.app\b/;
const SIGNATURE_CHECK =/hmac|signature|verify_?webhook|construct_?event|x-hub-signature|compare_digest|svix|webhooks?\.verify|jwt\.decode|oidc|id_token|authenticated|verify_\w*(token|request|push)/i;
const NEXT_GUARD = /getServerSession|\bauth\(\)|currentUser\(|getAuth\(|auth\.getUser|supabase\.auth\.get(User|Session)|getSession\(|verifyIdToken|jwt\.verify|jwtVerify|getToken\(|clerkClient|requireAuth|requireUser|withAuth|validateRequest|headers\(\)\.get\(\s*['"]authorization|status:\s*40[13]\b/;
@@ -292,6 +301,7 @@ function pyRoutes(src, f, out) {
else if (guardedVars.has(r.var)) Object.assign(rec, { guard: guardedVars.get(r.var), via: 'blueprint' });
else if (deps.some(isGuardDep)) Object.assign(rec, { guard: deps.find(isGuardDep), via: 'dependency' });
else if (INLINE_CHECK.test(body)) Object.assign(rec, { via: 'inline' });
+ else if (pyValidatedHeader(sig, body)) Object.assign(rec, { via: 'inline' });
else {
const misplaced = above.find((d) => isGuardName(d) && !/^(route|get|post|put|patch|delete)$/.test(d));
if (misplaced) rec.misplaced = misplaced;
diff --git a/tests/fixtures/fastapi-header-guard/app/main.py b/tests/fixtures/fastapi-header-guard/app/main.py
new file mode 100644
index 0000000..f4098d5
--- /dev/null
+++ b/tests/fixtures/fastapi-header-guard/app/main.py
@@ -0,0 +1,15 @@
+from fastapi import FastAPI, Header, HTTPException
+
+app = FastAPI()
+
+
[email protected]("/invites/checked")
+async def checked_invite(x_invite_token: str = Header(alias="X-Invite-Token")):
+ if x_invite_token != "server-side-expected":
+ raise HTTPException(status_code=403)
+ return {"ok": True}
+
+
[email protected]("/invites/unchecked")
+async def unchecked_invite(x_invite_token: str = Header(alias="X-Invite-Token")):
+ return {"received": bool(x_invite_token)}
diff --git a/tests/health.test.mjs b/tests/health.test.mjs
index 83cccb4..9a93316 100644
--- a/tests/health.test.mjs
+++ b/tests/health.test.mjs
@@ -44,6 +44,12 @@ test('FastAPI: Annotated dependency aliases count as sign-in checks (#4)', () =>
assert.deepEqual(openEndpoints(graph), ['POST /comments', 'POST /feedback']);
});
+test('FastAPI: header tokens are guarded only when the handler validates them (#7)', () => {
+ const graph = buildFixture('fastapi-header-guard');
+ assert.ok(graph.routes.some((r) => r.p === '/invites/checked'));
+ assert.deepEqual(openEndpoints(graph), ['POST /invites/unchecked']);
+});
+
test('FastAPI: checks added where a router is included count as sign-in checks', () => {
const graph = buildFixture('fastapi-include-router');
assert.equal(graph.routes.length, 4, `expected the sample's 4 endpoints, found ${graph.routes.length}`);