See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.
JavaScript ai-codingarchitecture-diagramclaudeclaude-codeclaude-code-plugincodebase-visualizationcodexcodex-plugindeveloper-toolsonboardingopenaivibe-coding
Health: recognise FastAPI Annotated dependency aliases as sign-in checks
Hayden Smithc014d0f09267
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c006947..6ca61f2 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -3,6 +3,7 @@## Unreleased- **Safari fix:** cards now show up in Safari (and every browser on iPhone/iPad). Before, only the connection lines were drawn and card text appeared in the top-left corner. Reported by @fpv001 in #1, fixed by @PaulMagos in #3.+- **Fewer false Health alarms on FastAPI:** endpoints protected through a shared dependency shortcut, like `user: AdminUser` where `AdminUser = Annotated[..., Depends(...)]`, are no longer reported as open to anyone. That includes shortcuts defined in another file, and shortcuts built on other shortcuts. A database session dependency (`SessionDep`, `get_db`) no longer counts as a login check, so endpoints that only have one are flagged as they should be. Reported by @PaulMagos in #4.## 0.1.3 (2026-10-28)diff --git a/skills/floorplan/scripts/lib/health.mjs b/skills/floorplan/scripts/lib/health.mjsindex 87c406e..8f4c334 100644--- a/skills/floorplan/scripts/lib/health.mjs+++ b/skills/floorplan/scripts/lib/health.mjs@@ -171,6 +171,9 @@ function findSecrets(src, f, out) {const GUARD_NAME = /(^|_)(login|auth|authenticated|authorized?|jwt|token|permission|permissions|perm|role|roles|staff|admin|superuser|owner|scope|scopes|session|api_?key|signature|signed|hmac|device|member|user)(_|$)|_required$|^requires?_|^ensure_|^verify_|^check_(auth|token|user|session|permission|role|api)|protect|^is_?authenticated|^is_?admin/i;const NOT_GUARD = /^(route|get|post|put|patch|delete|cached?|limit|limiter|rate_?limit\w*|cross_origin|wraps|staticmethod|classmethod|property|retry|timed|log\w*|swag_from|validate\w*|expects|marshal\w*|doc|json_required|fields?_required|params?_required|body_required|transaction\w*|csrf\w*|exempt)$/i;const isGuardName = (name) => !!name && !NOT_GUARD.test(name) && GUARD_NAME.test(snake(name));+// FastAPI dependencies that hand over a database session rather than check the caller (SessionDep, get_db)+const DB_DEPENDENCY = /^(get_|new_|create_)?(async_)?(db|database|session|db_session|sessionmaker)$|(^|_)(db|database)(_|$)/i;+const isGuardDep = (name) => isGuardName(name) && !DB_DEPENDENCY.test(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;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;@@ -198,7 +201,29 @@ function pyRoutes(src, f, out) {}for (const m of src.matchAll(/^\s*(\w+)\s*=\s*(?:\w+\.)?APIRouter\(([^)]*(?:\([^)]*\)[^)]*)*)\)/gm)) {const dep = /dependencies\s*=\s*\[[^\]]*Depends\(\s*([\w.]+)/.exec(m[2]);- if (dep && isGuardName(dep[1].split('.').pop())) guardedVars.set(m[1], dep[1]);+ if (dep && isGuardDep(dep[1].split('.').pop())) guardedVars.set(m[1], dep[1]);+ }+ // FastAPI dependency aliases, `AdminUser = Annotated[Session, Depends(admin_user)]`, and the dependency+ // functions behind them. They're usually imported from a shared deps.py, so build decides repo-wide+ // which ones check the caller (see pyAliasGuards).+ const lineAt = (i) => src.slice(0, i).split('\n').length - 1;+ const sigAt = (idx) => lines.slice(idx, idx + 15).join('\n').split(/\)\s*(->[^:]*)?:\s*$/m)[0];+ const depsIn = (text) => [...text.matchAll(/\b(?:Depends|Security)\(\s*([\w.]+)/g)].map((m) => m[1].split('.').pop());+ const typesIn = (sig) => [...new Set([...sig.matchAll(/\b\w+\s*:\s*(?:[\w.]*Annotated\[\s*)?([A-Za-z_][\w.]*)/g)].map((m) => m[1].split('.').pop()))];+ if (/\b(Depends|Security)\(/.test(src)) {+ for (const m of src.matchAll(/^(?:type\s+)?(\w+)\s*(?::[^=\n]*)?=\s*(?:[\w.]+\.)?Annotated\[/gm)) {+ let depth = 1, j = m.index + m[0].length;+ while (j < src.length && depth && j - m.index < 800) { if (src[j] === '[') depth++; else if (src[j] === ']') depth--; j++; }+ const fn = depsIn(src.slice(m.index, j))[0];+ if (fn) out.push({ k: 'py-alias', name: m[1], fn, line: lineAt(m.index) + 1 });+ }+ // top-level functions that aren't routes, with the dependencies and types they take+ for (const m of src.matchAll(/^(?:async\s+)?def\s+(\w+)\s*\(/gm)) {+ const idx = lineAt(m.index);+ if (idx > 0 && /^\s*@/.test(lines[idx - 1])) continue;+ const sig = sigAt(idx), deps = depsIn(sig), types = typesIn(sig);+ if (deps.length || types.length) out.push({ k: 'py-dep-fn', name: m[1], ...(deps.length ? { deps } : {}), ...(types.length ? { types } : {}) });+ }}// Decorators defined here: auth-named ones, and project wrappers like `@endpoint(write=True)` whose// body applies an auth decorator itself. Repeat once so a wrapper of a wrapper counts too.@@ -235,7 +260,7 @@ function pyRoutes(src, f, out) {const deps = [...(decoText + '\n' + sig).matchAll(dep)].map((m) => (m[1] || m[2]).split('.').pop());if (deco) Object.assign(rec, { guard: deco, via: 'decorator' });else if (guardedVars.has(r.var)) Object.assign(rec, { guard: guardedVars.get(r.var), via: 'blueprint' });- else if (deps.some(isGuardName)) Object.assign(rec, { guard: deps.find(isGuardName), via: 'dependency' });+ 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 {const misplaced = above.find((d) => isGuardName(d) && !/^(route|get|post|put|patch|delete)$/.test(d));@@ -243,6 +268,9 @@ function pyRoutes(src, f, out) {// other decorators may be auth wrappers defined in another file; build resolves themconst other = below.filter((d) => !/^(route|get|post|put|patch|delete|api_route|websocket)$/.test(d));if (other.length) rec.decos = other;+ // so may parameter types: `user: AdminUser`, a dependency alias (pyAliasGuards)+ const types = typesIn(sig);+ if (types.length) rec.types = types;}if (SIGNATURE_CHECK.test(body)) rec.signed = true;if (defIdx > 0) rec.fn = /def\s+(\w+)/.exec(lines[defIdx])[1];@@ -291,6 +319,33 @@ function jsRoutes(src, f, out) {});}+/**+ * FastAPI dependency aliases that check the caller, per repo: Map(repo -> Map(alias -> file)).+ * An alias checks the caller when its dependency function does: by its name (admin_user), by taking a+ * checking dependency (Depends(require_login)), or by taking a checking alias itself, e.g.+ * `AdminOffice = Annotated[Office, Depends(admin_owned_office)]` where admin_owned_office takes `admin: AdminUser`.+ */+function pyAliasGuards(files, findings) {+ const byRepo = new Map(); // repo -> { aliases: Map(name -> {fn, file}), fns: Map(name -> {deps, types}) }+ for (const f of files) for (const x of findings(f.path)) {+ if (x.k !== 'py-alias' && x.k !== 'py-dep-fn') continue;+ const k = f.repo ?? '';+ if (!byRepo.has(k)) byRepo.set(k, { aliases: new Map(), fns: new Map() });+ const r = byRepo.get(k);+ if (x.k === 'py-alias') r.aliases.set(x.name, { fn: x.fn, file: f.path });+ else r.fns.set(x.name, { deps: x.deps || [], types: x.types || [] });+ }+ const out = new Map();+ for (const [repo, { aliases, fns }] of byRepo) {+ const ok = new Map();+ const checks = (fn) => isGuardDep(fn) || (!DB_DEPENDENCY.test(fn) && !!fns.get(fn) && (fns.get(fn).deps.some(isGuardDep) || fns.get(fn).types.some((t) => ok.has(t))));+ // a few passes, so aliases built on other aliases resolve in any file order+ for (let pass = 0; pass < 3; pass++) for (const [name, a] of aliases) if (!ok.has(name) && checks(a.fn)) ok.set(name, a.file);+ if (ok.size) out.set(repo, ok);+ }+ return out;+}+// ---------- per-file entry point ----------export function findIssues(src, f) {@@ -459,6 +514,11 @@ export function buildHealth({ graph, scan, arch, root }) {if (x.k === 'global-guard' && !TEST_FILE.test(f.path) && !/(^|\/)(scripts?|tools|bin|examples?)\//.test(f.path) && !(fileByPath.has(f.path) && kinds(fileByPath.get(f.path).n).some((k) => NOT_USED_KINDS.has(k)))) { const k = f.repo ?? ''; if (!globalGuards.has(k)) globalGuards.set(k, []); globalGuards.get(k).push({ ...x, file: f.path }); }if (x.k === 'guard-def' && !TEST_FILE.test(f.path)) { if (!guardDefs.has(x.name)) guardDefs.set(x.name, []); guardDefs.get(x.name).push({ file: f.path, wrapper: !!x.wrapper }); }}+ const aliasGuards = pyAliasGuards(scan.files.filter((f) => !TEST_FILE.test(f.path)), findings);+ for (const [repo, aliases] of aliasGuards) for (const [name, file] of aliases) {+ if (!guardDefs.has(name)) guardDefs.set(name, []);+ guardDefs.get(name).push({ file, alias: true, repo });+ }// a sign-in check applied where the route's router is mounted: app.use('/admin', requireStaff, adminRouter)const mountGuard = new Map((scan.routes || []).filter((r) => r.mountMw?.some(isGuardName)).map((r) => [`${r.file}|${r.line}|${r.method}`, r.mountMw.find(isGuardName)]));const perRepo = new Map(); // repo -> { guarded, open: [], guardCounts }@@ -475,9 +535,11 @@ export function buildHealth({ graph, scan, arch, root }) {// an unrecognised decorator that turns out to be an auth wrapper defined elsewhere in the projectconst viaWrapper = !fnd.via && fnd.decos?.find((d) => guardDefs.get(d)?.some((g) => (g.file.split('/')[0] === r.f.split('/')[0])));const mounted = !fnd.via && mountGuard.get(`${r.f}|${r.l}|${r.m}`);- if (fnd.via || global || viaWrapper || mounted) {+ // a parameter typed with a dependency alias that checks the caller: `user: AdminUser`+ const viaAlias = !fnd.via && fnd.types?.find((t) => aliasGuards.get(repo)?.has(t));+ if (fnd.via || global || viaWrapper || mounted || viaAlias) {pr.guarded++; pr.guardedIn.set(r.f, (pr.guardedIn.get(r.f) || 0) + 1);- const name = fnd.guard || viaWrapper || mounted;+ const name = fnd.guard || viaWrapper || mounted || viaAlias;if (name) {pr.guardCounts.set(name, (pr.guardCounts.get(name) || 0) + 1);if (!pr.fileGuards.has(r.f)) pr.fileGuards.set(r.f, new Map());@@ -503,7 +565,8 @@ export function buildHealth({ graph, scan, arch, root }) {if (!name) return `the project's existing login check (find how other protected endpoints verify the user; if there is none, ask me before adding one)`;const defs = guardDefs.get(name) || [];const where = defs.find((g) => g.file === file) ? 'defined in this file' : defs.length ? `defined in ${defs[0].file}` : '';- return `the same check ${local ? 'the other endpoints in this file' : 'the protected endpoints'} already use (${lang === 'python' ? '@' : ''}${name}${where ? ', ' + where : ''})`;+ const how = defs.some((g) => g.alias) ? `a parameter typed ${name}` : `${lang === 'python' ? '@' : ''}${name}`;+ return `the same check ${local ? 'the other endpoints in this file' : 'the protected endpoints'} already use (${how}${where ? ', ' + where : ''})`;};const routeLine = (e) => `- ${e.r.m} ${e.r.p} — ${e.r.f}:${e.r.l}${e.fnd.fn && !/^[A-Z]+$/.test(e.fnd.fn) ? ` (${e.fnd.fn})` : ''}`;if (pr.misplaced.length) {diff --git a/tests/fixtures/fastapi-annotated/app/__init__.py b/tests/fixtures/fastapi-annotated/app/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/tests/fixtures/fastapi-annotated/app/deps.py b/tests/fixtures/fastapi-annotated/app/deps.pynew file mode 100644index 0000000..b03b103--- /dev/null+++ b/tests/fixtures/fastapi-annotated/app/deps.py@@ -0,0 +1,22 @@+"""Shared dependencies, imported by the routers (the common FastAPI layout)."""+from typing import Annotated++from fastapi import Depends, Header, HTTPException+from sqlmodel import Session, create_engine++engine = create_engine("sqlite://")+++def get_session():+ with Session(engine) as session:+ yield session+++def admin_user_dependency(authorization: str = Header(...)):+ if authorization != "Bearer admin":+ raise HTTPException(status_code=401)+ return {"role": "admin"}+++SessionDep = Annotated[Session, Depends(get_session)]+AdminUser = Annotated[dict, Depends(admin_user_dependency)]diff --git a/tests/fixtures/fastapi-annotated/app/main.py b/tests/fixtures/fastapi-annotated/app/main.pynew file mode 100644index 0000000..5c4747c--- /dev/null+++ b/tests/fixtures/fastapi-annotated/app/main.py@@ -0,0 +1,9 @@+from fastapi import FastAPI++from app.routers import feedback, notes, offices, things++app = FastAPI()+app.include_router(things.router)+app.include_router(notes.router)+app.include_router(offices.router)+app.include_router(feedback.router)diff --git a/tests/fixtures/fastapi-annotated/app/routers/__init__.py b/tests/fixtures/fastapi-annotated/app/routers/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/tests/fixtures/fastapi-annotated/app/routers/feedback.py b/tests/fixtures/fastapi-annotated/app/routers/feedback.pynew file mode 100644index 0000000..199e914--- /dev/null+++ b/tests/fixtures/fastapi-annotated/app/routers/feedback.py@@ -0,0 +1,11 @@+"""Really open: only a database session, no sign-in check. Health must still flag it."""+from fastapi import APIRouter++from app.deps import SessionDep++router = APIRouter()++[email protected]("/feedback")+async def send_feedback(message: str, db: SessionDep):+ return {"ok": True}diff --git a/tests/fixtures/fastapi-annotated/app/routers/notes.py b/tests/fixtures/fastapi-annotated/app/routers/notes.pynew file mode 100644index 0000000..30dd791--- /dev/null+++ b/tests/fixtures/fastapi-annotated/app/routers/notes.py@@ -0,0 +1,20 @@+"""Same-file alias: guarded through MemberUser, defined here."""+from typing import Annotated++from fastapi import APIRouter, Depends, Header, HTTPException++router = APIRouter()+++def check_member(x_member_token: str = Header(...)):+ if not x_member_token:+ raise HTTPException(status_code=401)+ return {"member": True}+++MemberUser = Annotated[dict, Depends(check_member)]++[email protected]("/notes")+async def add_note(text: str, member: MemberUser):+ return {"text": text}diff --git a/tests/fixtures/fastapi-annotated/app/routers/offices.py b/tests/fixtures/fastapi-annotated/app/routers/offices.pynew file mode 100644index 0000000..7490e09--- /dev/null+++ b/tests/fixtures/fastapi-annotated/app/routers/offices.py@@ -0,0 +1,20 @@+"""Nested alias: OwnedOffice's dependency takes AdminUser itself."""+from typing import Annotated++from fastapi import APIRouter, Depends++from app.deps import AdminUser++router = APIRouter()+++def load_office(office_id: int, admin: AdminUser):+ return {"id": office_id}+++OwnedOffice = Annotated[dict, Depends(load_office)]++[email protected]("/offices/{office_id}")+async def rename_office(office_id: int, name: str, office: OwnedOffice):+ return {"id": office_id, "name": name}diff --git a/tests/fixtures/fastapi-annotated/app/routers/things.py b/tests/fixtures/fastapi-annotated/app/routers/things.pynew file mode 100644index 0000000..0a10d7d--- /dev/null+++ b/tests/fixtures/fastapi-annotated/app/routers/things.py@@ -0,0 +1,16 @@+"""Imported alias: guarded through AdminUser from app.deps."""+from fastapi import APIRouter++from app.deps import AdminUser, SessionDep++router = APIRouter()++[email protected]("/admin/things")+async def create_thing(name: str, user: AdminUser, db: SessionDep):+ return {"name": name}++[email protected]("/admin/things/{thing_id}")+async def delete_thing(thing_id: int, user: AdminUser):+ return {"deleted": thing_id}diff --git a/tests/health.test.mjs b/tests/health.test.mjsnew file mode 100644index 0000000..450c2b4--- /dev/null+++ b/tests/health.test.mjs@@ -0,0 +1,44 @@+// Health check regression tests: build a map of a small sample project and check which endpoints+// Health reports as open to anyone. Run with: node --test tests/+import { test } from 'node:test';+import assert from 'node:assert/strict';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { execFileSync } from 'node:child_process';+import { fileURLToPath } from 'node:url';++const here = path.dirname(fileURLToPath(import.meta.url));+const scripts = path.join(here, '..', 'skills', 'floorplan', 'scripts');++/** Copies a fixture to a temp folder, maps it as one module, and returns the built graph. */+function buildFixture(name) {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), `floorplan-${name}-`));+ fs.cpSync(path.join(here, 'fixtures', name), root, { recursive: true });+ fs.mkdirSync(path.join(root, 'floorplan'));+ fs.writeFileSync(path.join(root, 'floorplan', 'architecture.json'), JSON.stringify({+ project: { name, summary: 'Test fixture.' },+ nodes: [{ id: 'api', label: 'Server', kind: 'service', summary: 'The sample server.', paths: ['**'] }],+ }));+ for (const s of ['scan.mjs', 'build.mjs']) execFileSync(process.execPath, [path.join(scripts, s), root, '--no-claude-md'], { stdio: 'pipe' });+ const graph = JSON.parse(fs.readFileSync(path.join(root, 'floorplan', 'graph.json'), 'utf8'));+ fs.rmSync(root, { recursive: true, force: true });+ return graph;+}++/** "METHOD /path" for every endpoint Health reports as callable by anyone. */+function openEndpoints(graph) {+ return graph.health.issues+ .filter((i) => i.kind === 'unprotected-endpoint')+ .flatMap((i) => i.items.filter((id) => id.startsWith('r:')).map((id) => graph.routes[+id.slice(2)]))+ .map((r) => `${r.m} ${r.p}`)+ .sort();+}++test('FastAPI: Annotated dependency aliases count as sign-in checks (#4)', () => {+ const graph = buildFixture('fastapi-annotated');+ assert.ok(graph.routes.length >= 5, `expected the sample's 5 endpoints, found ${graph.routes.length}`);+ // imported alias (AdminUser), same-file alias (MemberUser) and an alias whose dependency takes+ // AdminUser (OwnedOffice) are all protected; a route with only a database session (SessionDep) isn't+ assert.deepEqual(openEndpoints(graph), ['POST /feedback']);+});