Skip to content

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

Health: fewer false alarms on public feeds, Payload CMS, POST-only replies, tracker tokens and files tools open by name

Hayden Smith9f75896377f1
diff --git a/skills/floorplan/scripts/lib/health.mjs b/skills/floorplan/scripts/lib/health.mjs
index 5ce21db..b7a94c0 100644
--- a/skills/floorplan/scripts/lib/health.mjs
+++ b/skills/floorplan/scripts/lib/health.mjs
@@ -125,6 +125,20 @@ function valueLooksReal(v, name) {
// beacon (data-cf-beacon='{"token":"…"}') and Mapbox public tokens (pk.…)
const PUBLIC_TOKEN_LINE = /data-cf-beacon|cloudflareinsights\.com/i;
const PUBLIC_TOKEN_VALUE = /^pk\.[\w-]{20,}\.[\w-]{10,}$/;
+// A site token handed to a browser tracker's script: the script reads it from the page, so every visitor has it.
+// Names that say more than "token" (access, auth, secret…) and real key formats are never excused this way.
+const SCRIPT_TAG = /<script\b|createElement\(\s*['"]script['"]\s*\)/i;
+const TRACKER_FILE = /analytics|tracker|tracking|beacon|pixel|telemetry/i;
+const NOT_SITE_TOKEN = /secret|passw|private|access|refresh|auth|bearer|api_?key|signing/i;
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+function trackerToken(name, value, src, file) {
+ const n = snake(name);
+ if (!/token$/.test(n) || NOT_SITE_TOKEN.test(n) || !SCRIPT_TAG.test(src)) return false;
+ if (TRACKER_FILE.test(file.split('/').pop())) return true;
+ const id = escapeRe(name), val = escapeRe(value);
+ return new RegExp('<script\\b[^>]*\\bdata-[\\w-]+\\s*=\\s*(?:\\{\\s*' + id + '\\s*\\}|["\'`]' + val + ')', 'i').test(src)
+ || new RegExp('dataset\\.\\w+\\s*=\\s*' + id + '\\b|setAttribute\\(\\s*[\'"]data-[\\w-]+[\'"]\\s*,\\s*' + id + '\\b').test(src);
+}
/** 1-based line numbers inside docstrings or block comments (examples there aren't real config). */
function docLines(src, lang) {
@@ -186,6 +200,7 @@ function findSecrets(src, f, out) {
for (const [name, value] of pairs) {
const n = snake(name.split('.').pop());
if (!SECRET_NAME.test(n) || PUBLIC_NAME.test(n) || PUBLIC_TOKEN_VALUE.test(value) || !valueLooksReal(value, n)) continue;
+ if (trackerToken(name.split('.').pop(), value, src, f.path)) continue;
if (throwawayDb && /^(postgres|mysql|mariadb|mongo(_initdb_root)?|redis|pg|rabbitmq_default|db|database)_(root_)?(password|pass|pwd)$/.test(n)) continue;
add(i + 1, { what: kindFromName(name), name: name.split('.').pop(), sev: 'high', hint: mask(value, PASSWORD_NAME.test(n)), generic: true });
}
@@ -204,7 +219,7 @@ const DB_DEPENDENCY = /^(get_|new_|create_)?(async_)?(db|database|session|db_ses
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;
+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\(|\b(?:verify|check|require|validate|authenticate|authorize)\w*(?:Auth|Token|Session|Signature|Webhook|Hmac|Jwt|Secret|Permission|Role)\w*\s*\(|\bis_?(?:[Vv]alid_?)?(?:[Aa]uthorized|[Aa]uthenticated|[Ss]ignature|[Tt]oken|[Ss]ecret|[Aa]pi_?[Kk]ey)\w*\s*\(|timingSafeEqual|safeCompare|[!=]==?\s*(?:[`'"]Bearer\s+\$\{\s*)?process\.env\.\w*(?:SECRET|TOKEN|KEY|PASSWORD)|process\.env\.\w*(?:SECRET|TOKEN|KEY|PASSWORD)\w*\s*[!=]==?/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) {
@@ -217,6 +232,26 @@ function pyValidatedHeader(sig, 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/;
+// A response marked to be stored and served to everyone can't hold one caller's data.
+const PUBLIC_RESPONSE = /cache-control['"]?\]?\s*[:,=]\s*[`'"f]*[^`'"\n]*\b(?:public|s-maxage)\b/i;
+const PRIVATE_RESPONSE = /cache-control['"]?\]?\s*[:,=]\s*[`'"f]*[^`'"\n]*\b(?:private|no-store)\b/i;
+const NEXT_STATIC = /\bdynamic\s*=\s*['"]force-static['"]|export\s+const\s+revalidate\s*=\s*[1-9]/;
+// API routes from a library that checks access itself: Payload CMS generates these and applies its collections' access rules
+const SELF_CHECKING_ROUTES = /from\s+['"]@payloadcms\/next\/routes['"]/;
+// Where a Next.js GET could get something worth protecting from: a data store, the caller's session, or a server-side secret
+const READS_PRIVATE = /\b(?:prisma\w*|drizzle\w*|mongoose|mongodb|sequelize|typeorm|knex|kysely|supabase|firestore|firebase-admin|firebase\/\w+|dynamodb|redis|upstash|postgres|pg|mysql2?|sqlite3?|payload\w*|neon|turso|libsql)\b|\bdb\s*[.(]|\bdatabase\s*\.|\.(?:findMany|findUnique|findFirst|findOne|findAll|query|execute)\s*\(|\bcookies\s*\(|\bgetServerSession\b|\.session\b|\breq(?:uest)?\.(?:user|auth)\b|process\.env\.(?!NEXT_PUBLIC_|NODE_ENV\b|VERCEL|PUBLIC_|SITE_URL\b|BASE_URL\b|APP_URL\b)\w+/i;
+const READS_FILES = /\b(?:readFile(?:Sync)?|createReadStream|readdir(?:Sync)?)\b/;
+// Helpers around a route that don't feed what it returns
+const NOT_ITS_DATA = /(^|\/)[^/]*(rate-?limit|limiter|logger|logging|metrics|telemetry|sentry|analytics)[^/]*$/i;
+const METHOD_NOT_ALLOWED = /status(?:Code)?\s*[:=(]\s*405\b|\.status\(\s*405\b|\bmethodNotAllowed\b/i;
+/** The code of one exported handler in a Next.js route file. */
+function nextHandler(src, method) {
+ const m = new RegExp('^[ \\t]*export\\s+(?:async\\s+)?(?:function|const)\\s+' + method + '\\b', 'm').exec(src);
+ if (!m) return '';
+ const rest = src.slice(m.index + m[0].length);
+ const end = rest.search(/^[ \t]*export\s/m);
+ return end < 0 ? rest : rest.slice(0, end);
+}
const NEXT_MIDDLEWARE_GUARD = /getToken|withAuth|clerkMiddleware|authMiddleware|auth\(|supabase|getSession|jwtVerify|jwt\.verify|cookies\.get\([^)]*(session|token|auth)|redirect\([^)]*login/i;
function blockAfter(lines, defIdx) {
@@ -325,6 +360,7 @@ function pyRoutes(src, f, out) {
}
if (body) rec.calls = [...new Set([...body.matchAll(/\b(?:await\s+)?([A-Za-z_]\w*)\s*\(/g)].map((m) => m[1]))];
if (SIGNATURE_CHECK.test(body)) rec.signed = true;
+ if (PUBLIC_RESPONSE.test(body)) rec.publicResponse = true;
if (defIdx > 0) rec.fn = /def\s+(\w+)/.exec(lines[defIdx])[1];
out.push(rec);
}
@@ -361,8 +397,12 @@ function jsRoutes(src, f, out) {
return;
}
if (r.framework === 'next') {
- if (NEXT_GUARD.test(src)) rec.via = 'inline';
+ if (SELF_CHECKING_ROUTES.test(src)) rec.via = 'library';
+ else if (NEXT_GUARD.test(src) || INLINE_CHECK.test(src)) rec.via = 'inline';
if (SIGNATURE_CHECK.test(src)) rec.signed = true;
+ const handler = nextHandler(src, r.method);
+ if (METHOD_NOT_ALLOWED.test(handler) && !READS_PRIVATE.test(handler)) rec.notAllowed = true;
+ if (r.method === 'GET') rec.nextGet = true;
rec.fn = r.method;
out.push(rec);
return;
@@ -387,6 +427,7 @@ function jsRoutes(src, f, out) {
else if (prior) Object.assign(rec, { guard: prior.name, via: 'router' });
else if (INLINE_CHECK.test(body)) rec.via = 'inline';
if (SIGNATURE_CHECK.test(body)) rec.signed = true;
+ if (PUBLIC_RESPONSE.test(body)) rec.publicResponse = true;
out.push(rec);
});
}
@@ -578,11 +619,21 @@ export function findIssues(src, f) {
const SEV_ORDER = { high: 0, medium: 1, low: 2 };
const PUBLIC_PATH = /(^|\/)(health|healthz|healthcheck|ping|status|ready|readyz|readiness|live|livez|liveness|version|metrics|robots\.txt|sitemap[\w.]*|favicon[\w.]*|\.well-known|login|logout|signin|pair|sign-in|signout|signup|sign-up|register|forgot[\w-]*|reset[\w-]*|verify[\w-]*|oauth\w*|callback|auth|token|refresh|static|assets|public|newsletter|contact|waitlist|unsubscribe|openapi\.json|docs|swagger[\w.]*|i|images?)(\/|$)/i;
+// Files and feeds that exist to be read by crawlers, feed readers and AI tools. Only for reading: see publicByDesign.
+const PUBLIC_FILE_PATH = /(^|\/)(llms(-full)?\.txt|ai\.txt|humans\.txt|(app-)?ads\.txt|security\.txt|rss(\.xml)?|atom(\.xml)?|feed\.(xml|rss|atom|json)|index\.xml|opensearch\.xml|site\.webmanifest|manifest\.(json|webmanifest)|openapi\.ya?ml)$/i;
+const LISTING_FILE = /(^|\/)(llms(-full)?\.txt|robots\.txt)$/i;
+/** The addresses a project publishes in its llms.txt, or explicitly allows in its robots.txt. */
+function listedPaths(file, src) {
+ const found = /robots\.txt$/i.test(file) ? [...src.matchAll(/^\s*Allow:\s*(\/\S*)/gim)] : [...src.matchAll(/(?:https?:\/\/[^\s/)\]"'<>]+|(?<![\w./-]))(\/[^\s)\]"'<>#?*]+)/g)];
+ return found.map((m) => m[1].replace(/[.,;:]+$/, '').replace(/\/$/, '')).filter((p) => p.length > 1 && !p.includes('*'));
+}
const WEBHOOK_PATH = /webhook|\/hooks?\//i;
// endpoints under a webhook URL that manage the webhooks (create, list, test…) rather than receive them
const WEBHOOK_ADMIN = /\/(manage|admin|setup|settings|config|list|create|register|delete|test[\w-]*)(\/|$)/i;
const NOT_USED_KINDS = new Set(['test', 'script', 'infra', 'config', 'worker', 'external']);
const SPECIAL_FILE = /(^|\/)(index|main|app|server|cli|manage|wsgi|asgi|__init__|__main__|conftest|setup|config|settings|env|middleware|instrumentation|layout|page|route|loading|error|not-found|template|default|global-error|sitemap|robots|manifest|opengraph-image|twitter-image|icon|apple-icon|_app|_document|_error|404|500|models|admin|apps|views|urls|signals|tasks|forms|serializers|celery|gunicorn\.conf|vite-env\.d|worker|sw|service-worker)\.[a-z]+$|\.d\.ts$|\.config\.[a-z]+$|\.stories\.|(^|\/)(pages|migrations|alembic|versions|scripts|bin|tools|seeds?|fixtures?|examples?|docs?|public|static|templates|\.github|e2e|cypress|playwright)\//i;
+// A comment saying a tool opens this file by name, or that it's generated: not leftover code, whatever imports it
+const LOADED_BY_NAME = /^\s*(?:\/\/|\/?\*|#|<!--|"""|''')[^\n]*(?:\b(?:cli|tool|tooling|framework|runner|bundler|build|compiler|plugin|sdk|script)\b[^\n]*\b(?:reads?|loads?|imports?|runs?|executes?|opens?|requires?|picks? up)\b[^\n]*\b(?:this file|directly|by name|by path|at runtime)\b|\bthis file is (?:read|loaded|imported|run|executed|required|used|picked up)\b[^\n]*\b(?:by|directly|at runtime)\b|\bthis (?:file|code) (?:is|was) (?:auto-?)?generated\b|@generated\b|\b(?:auto-?)?generated (?:file|code)\b|\bcode generated by\b|\bdo not (?:edit|modify|delete|remove) (?:this|it)\b)/im;
const USED_LANGS = new Set(['typescript', 'javascript', 'python', 'vue', 'svelte', 'astro']);
const plural = (n, w, ws) => `${n} ${n === 1 ? w : ws || w + 's'}`;
@@ -1013,6 +1064,55 @@ export function buildHealth({ graph, scan, arch, root }) {
// a sign-in check applied where the route's router is mounted: app.use('/admin', requireStaff, adminRouter),
// or app.include_router(admin.router, dependencies=[Depends(require_admin)]) (a database session isn't one)
const mountGuard = new Map((scan.routes || []).filter((r) => r.mountMw?.some(isGuardDep)).map((r) => [`${r.file}|${r.line}|${r.method}`, r.mountMw.find(isGuardDep)]));
+ const sourceOf = new Map();
+ const readSource = (p) => {
+ if (!sourceOf.has(p)) { let src = ''; try { src = readHead(path.join(root, p), 262144); } catch { /* unreadable: nothing to go on */ } sourceOf.set(p, src); }
+ return sourceOf.get(p);
+ };
+ const published = new Map(); // repo -> addresses it lists for crawlers and AI tools
+ for (const f of scan.files) {
+ if (!LISTING_FILE.test(f.path) || TEST_FILE.test(f.path) || EXAMPLE_FILE.test(f.path)) continue;
+ const k = f.repo ?? '';
+ if (!published.has(k)) published.set(k, new Set());
+ for (const p of listedPaths(f.path, readSource(f.path))) published.get(k).add(p);
+ }
+ const isListed = (repo, p) => {
+ const listed = published.get(repo);
+ if (!listed) return false;
+ if (listed.has(p)) return true;
+ if (!/\[\.\.\./.test(p)) return false; // a catch-all route covers what's listed under it
+ const prefix = p.split('[')[0];
+ return prefix.length > 1 && [...listed].some((x) => x.startsWith(prefix));
+ };
+ const importsOf = new Map();
+ for (const l of graph.links) if (l.a !== l.b && l.a.startsWith('f:') && l.b.startsWith('f:')) { const a = l.a.slice(2); if (!importsOf.has(a)) importsOf.set(a, new Set()); importsOf.get(a).add(l.b.slice(2)); }
+ const PROJECT_IMPORT = /\bfrom\s+['"](?:\.{1,2}\/|@\/|~\/|#)|\bimport\s*\(\s*['"](?:\.{1,2}\/|@\/|~\/|#)|\brequire\(\s*['"](?:\.{1,2}\/|@\/|~\/|#)/g;
+ /** A Next.js route file whose code, and everything it imports, shows no data store, session or server secret. */
+ const readsNothingPrivate = (file, dynamic) => {
+ const seen = new Set([file]), queue = [file];
+ while (queue.length) {
+ const p = queue.pop();
+ const src = readSource(p);
+ if (READS_PRIVATE.test(src) || (dynamic && READS_FILES.test(src))) return false;
+ const next = [...(importsOf.get(p) || [])];
+ // an import we couldn't follow could hold anything
+ if ((src.match(PROJECT_IMPORT) || []).length > next.length) return false;
+ for (const n of next) if (!seen.has(n) && !NOT_ITS_DATA.test(n)) { seen.add(n); queue.push(n); }
+ if (seen.size > 200) return false;
+ }
+ return true;
+ };
+ const marksPublic = (file) => {
+ const src = readSource(file);
+ if (PUBLIC_RESPONSE.test(src) || NEXT_STATIC.test(src)) return true;
+ return [...(importsOf.get(file) || [])].some((p) => { const h = readSource(p); return PUBLIC_RESPONSE.test(h) && !PRIVATE_RESPONSE.test(h); });
+ };
+ /** A reading endpoint that's open on purpose: its address, the project's own listing, its response, or having nothing private to give. */
+ const publicByDesign = (r, fnd, repo) => {
+ if (r.m !== 'GET') return false;
+ if (PUBLIC_FILE_PATH.test(r.p) || isListed(repo, r.p) || fnd.publicResponse) return true;
+ return !!fnd.nextGet && (marksPublic(r.f) || readsNothingPrivate(r.f, /\[/.test(r.p)));
+ };
const perRepo = new Map(); // repo -> { guarded, open: [], guardCounts }
graph.routes.forEach((r, i) => {
const fnd = routeFinding.get(`${r.f}|${r.l}|${r.m}`);
@@ -1041,7 +1141,7 @@ export function buildHealth({ graph, scan, arch, root }) {
}
return;
}
- if (r.m === 'OPTIONS' || r.m === 'HEAD') return;
+ if (r.m === 'OPTIONS' || r.m === 'HEAD' || fnd.notAllowed) return;
// webhook receivers: by URL, or a webhook-ish handler in a webhook file (not that file's admin endpoints)
const webhook = (WEBHOOK_PATH.test(r.p) && !WEBHOOK_ADMIN.test(r.p)) || (/webhook|hooks?\//i.test(r.f) && /webhook|hook|notify|event|ingress|pubsub|callback|receive|inbound/i.test(r.h || '') && !/create|list|manage|register|delete|test|setup|sync/i.test((r.h || '') + r.p));
if (webhook && fnd.signed) return;
@@ -1049,6 +1149,7 @@ export function buildHealth({ graph, scan, arch, root }) {
if (stripeFiles.has(r.f) && (webhook || /stripe|payment|hook/i.test(r.p) || graph.routes.filter((x) => x.f === r.f && x.m !== 'GET').length === 1)) return;
if (!webhook && PUBLIC_PATH.test(r.p.replace(/<[^>]*>|\{[^}]*\}|:\w+|\[[^\]]*\]/g, 'x'))) return;
if (r.p === '/' && r.m === 'GET') return;
+ if (!webhook && publicByDesign(r, fnd, repo)) return;
const entry = { i, r, fnd, write: !['GET', 'ANY'].includes(r.m), webhook };
if (fnd.misplaced) pr.misplaced.push(entry); else pr.open.push(entry);
});
@@ -1154,7 +1255,7 @@ export function buildHealth({ graph, scan, arch, root }) {
try { src = fs.readFileSync(path.join(root, f.path), 'utf8'); } catch { continue; }
for (const tok of new Set(src.match(/[\w$-]+/g) || [])) { const p = want.get(tok); if (p && p !== f.path) mentioned.add(p); }
}
- const unused = candidates.filter((f) => !mentioned.has(f.p));
+ const unused = candidates.filter((f) => !mentioned.has(f.p) && !LOADED_BY_NAME.test(readSource(f.p).split('\n', 20).join('\n')));
// A module where most files look unused is more likely loaded in a way we can't see; stay quiet.
const byNode = new Map();
for (const f of unused) { if (!byNode.has(f.n)) byNode.set(f.n, []); byNode.get(f.n).push(f); }
diff --git a/tests/public-by-design.test.mjs b/tests/public-by-design.test.mjs
new file mode 100644
index 0000000..cec906d
--- /dev/null
+++ b/tests/public-by-design.test.mjs
@@ -0,0 +1,235 @@
+// False alarms people reported from the Health tab's "Not a problem" dialog (#40-#52). Most came from one site:
+// feeds, fact sheets and files written for search engines and AI tools, a CMS's own API, a webhook's "POST only"
+// reply. Each case comes with its near miss, because a check that goes quiet on real problems is worse than a noisy one.
+// Secret-looking values are assembled at runtime so none is ever committed to this repo.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { lib, makeProject, scanAndBuild, readGraph, openEndpoints, cleanup } from './helpers.mjs';
+
+const { findIssues } = await lib('health.mjs');
+const ARCH = { project: { name: 'Site', summary: 'A sample site.' }, nodes: [{ id: 'site', label: 'Site', kind: 'service', summary: 'The site.', paths: ['**'] }] };
+const route = (path) => `src/app/${path}/route.ts`;
+const STATIC_JSON = `export async function GET() { return Response.json({ name: 'Sample', plans: ['free', 'pro'] }); }\n`;
+// one protected endpoint, so these tests look at the per-file issues rather than "nothing here checks logins"
+const GUARDED = {
+ 'package.json': '{"name":"site","dependencies":{"next":"15"}}',
+ 'tsconfig.json': '{"compilerOptions":{"baseUrl":".","paths":{"@/*":["src/*"]}}}',
+ [route('api/account')]: `import { getServerSession } from 'next-auth';\nexport async function GET() { const s = await getServerSession(); return Response.json(s); }\n`,
+};
+
+/** Maps a small Next.js project and returns the graph. */
+function build(files) {
+ const root = makeProject({ ...GUARDED, ...files }, { arch: ARCH });
+ try { scanAndBuild(root); return readGraph(root); } finally { cleanup(root); }
+}
+const open = (files) => openEndpoints(build(files));
+
+// ---------- feeds and files that exist to be read by anyone (#41, #49) ----------
+test('feeds and files for crawlers and AI tools are public by their address', () => {
+ const addresses = ['blog/rss.xml', 'blog/atom.xml', 'blog/feed.xml', 'rss', 'v1/llms.txt', 'llms-full.txt', 'ads.txt', 'humans.txt'];
+ const found = open(Object.fromEntries(addresses.map((a) => [route(a), `import { posts } from '@/lib/db';\nexport async function GET() { return new Response(await posts()); }\n`])));
+ assert.deepEqual(found, []);
+});
+
+test('that address only excuses reading it, and a social "feed" is not a public file', () => {
+ const dbRead = `import { db } from '@/lib/db';\nexport async function GET() { return Response.json(await db.post.findMany()); }\n`;
+ assert.deepEqual(open({ [route('api/feed')]: dbRead }), ['GET /api/feed']);
+ assert.deepEqual(open({ [route('blog/rss.xml')]: `export async function POST(req: Request) { return Response.json(await req.json()); }\n` }), ['POST /blog/rss.xml']);
+});
+
+// ---------- the project itself says it's public (#44, #47, #48, #51, #52) ----------
+const dataFeed = `import { db } from '@/lib/db';\nexport async function GET() { return Response.json(await db.plan.findMany()); }\n`;
+
+test('an endpoint the project lists in its llms.txt or allows in robots.txt is public on purpose', () => {
+ const files = {
+ [route('v1/pricing.json')]: dataFeed, [route('v1/facts.txt')]: dataFeed, [route('v1/resources.json')]: dataFeed,
+ [route('api/pages/[[...slug]]')]: dataFeed,
+ 'public/llms.txt': '# Sample\n- [Pricing](https://example.com/v1/pricing.json): plans\n- [Facts](/v1/facts.txt)\n- Pages as text: https://example.com/api/pages/about\n',
+ 'public/robots.txt': 'User-agent: *\nAllow: /v1/resources.json\nDisallow: /api/\n',
+ };
+ assert.deepEqual(open(files), []);
+});
+
+test('being blocked in robots.txt, being only near a listed address, or changing data does not count', () => {
+ const files = {
+ [route('api/private.json')]: dataFeed, [route('v1/pricing.json/details')]: dataFeed, [route('v1/stats')]: dataFeed,
+ [route('v1/leads.json')]: `import { db } from '@/lib/db';\nexport async function POST(req: Request) { return Response.json(await db.lead.create({ data: await req.json() })); }\n`,
+ 'public/llms.txt': '- [Pricing](/v1/pricing.json)\n- [Leads](/v1/leads.json)\n',
+ 'public/robots.txt': 'User-agent: *\nAllow: /\nDisallow: /api/private.json\n',
+ };
+ assert.deepEqual(open(files), ['GET /api/private.json', 'GET /v1/pricing.json/details', 'GET /v1/stats', 'POST /v1/leads.json']);
+});
+
+test('a catch-all route needs a listed address under it, and "/" alone never covers everything', () => {
+ const files = { [route('[...slug]')]: dataFeed, 'public/robots.txt': 'User-agent: *\nAllow: /\n', 'public/llms.txt': 'See https://example.com/ for more.\n' };
+ assert.deepEqual(open(files), ['GET /[...slug]']);
+});
+
+test('a listing in another repo says nothing about this one', () => {
+ const root = makeProject({
+ 'web/package.json': '{"name":"web","dependencies":{"next":"15"}}',
+ 'web/public/llms.txt': '- [Stats](/v1/stats)\n',
+ 'api/package.json': '{"name":"api","dependencies":{"next":"15"}}',
+ 'api/src/app/v1/stats/route.ts': dataFeed,
+ 'api/src/app/api/account/route.ts': GUARDED[route('api/account')],
+ }, { repos: ['web', 'api'], arch: ARCH });
+ try { scanAndBuild(root); assert.deepEqual(openEndpoints(readGraph(root)), ['GET /v1/stats']); } finally { cleanup(root); }
+});
+
+// ---------- a response marked for everyone (#48, #49) ----------
+test('a response cached for everyone is public on purpose, including through its helper', () => {
+ const files = {
+ [route('v1/product.json')]: `import { db } from '@/lib/db';\nexport async function GET() { return new Response(JSON.stringify(await db.plan.findMany()), { headers: { 'Cache-Control': 'public, max-age=3600' } }); }\n`,
+ [route('v1/sheet.txt')]: `import { db } from '@/lib/db';\nexport const dynamic = 'force-static';\nexport async function GET() { return new Response(await db.sheet()); }\n`,
+ [route('v1/hourly.json')]: `import { db } from '@/lib/db';\nexport const revalidate = 3600;\nexport async function GET() { return Response.json(await db.sheet()); }\n`,
+ [route('v1/helper.json')]: `import { db } from '@/lib/db';\nimport { publicJson } from '@/lib/public-json';\nexport async function GET() { return publicJson(await db.sheet()); }\n`,
+ 'src/lib/public-json.ts': `export const publicJson = (body: unknown) => Response.json(body, { headers: { 'cache-control': 'public, s-maxage=600' } });\n`,
+ 'src/lib/db.ts': `import { PrismaClient } from '@prisma/client';\nexport const db = new PrismaClient();\n`,
+ };
+ assert.deepEqual(open(files), []);
+});
+
+test('a private response, or one open to other sites but not cached, is not public by that alone', () => {
+ const files = {
+ [route('api/me.json')]: `import { db } from '@/lib/db';\nexport async function GET() { return new Response(JSON.stringify(await db.user.first()), { headers: { 'Cache-Control': 'private, no-store' } }); }\n`,
+ [route('api/open.json')]: `import { db } from '@/lib/db';\nexport async function GET() { return new Response(JSON.stringify(await db.user.first()), { headers: { 'Access-Control-Allow-Origin': '*' } }); }\n`,
+ [route('api/nocache.json')]: `import { db } from '@/lib/db';\nexport const revalidate = 0;\nexport async function GET() { return Response.json(await db.user.first()); }\n`,
+ };
+ assert.deepEqual(open(files), ['GET /api/me.json', 'GET /api/nocache.json', 'GET /api/open.json']);
+});
+
+// ---------- reads nothing private (#45, #46, #47, #52) ----------
+test('a Next.js GET that reads no database, session or secret has no data to protect', () => {
+ const files = {
+ [route('v1/policy.json')]: STATIC_JSON,
+ [route('v1/product.json')]: `export async function GET() { return Response.json({ pricing: process.env.NEXT_PUBLIC_PRICING, env: process.env.NODE_ENV }); }\n`,
+ [route('api/campaign/countdown')]: `const END = Date.parse('2026-12-01');\nexport async function GET() { return Response.json({ left: END - Date.now() }); }\n`,
+ [route('v1/links.json')]: `import { LINKS } from '@/lib/links';\nexport async function GET() { return Response.json(LINKS); }\n`,
+ 'src/lib/links.ts': `export const LINKS = ['/docs', '/pricing'];\n`,
+ // a rate limiter keeps its counts in Redis, but that isn't what the endpoint returns
+ [route('v1/limited.json')]: `import { consumeRateLimit } from '@/lib/rate-limit';\nexport async function GET(req: Request) { await consumeRateLimit(req); return Response.json({ ok: true }); }\n`,
+ 'src/lib/rate-limit.ts': `import { Redis } from '@upstash/redis';\nconst r = Redis.fromEnv();\nexport const consumeRateLimit = (req: Request) => r.incr(req.url);\n`,
+ [route('api/pages/[[...slug]]')]: `import { PAGES } from '@/lib/pages';\nexport async function GET(_: Request, { params }: { params: { slug: string[] } }) { const p = PAGES[params.slug.join('/')]; return p ? new Response(p) : new Response('', { status: 404 }); }\n`,
+ 'src/lib/pages.ts': `export const PAGES: Record<string, string> = { about: 'About us' };\n`,
+ };
+ assert.deepEqual(open(files), []);
+});
+
+test('reading a database, session, cookie, secret or a file chosen by the caller, even through an import, still counts', () => {
+ const files = {
+ [route('api/users')]: `import { prisma } from '@/lib/prisma';\nexport async function GET() { return Response.json(await prisma.user.findMany()); }\n`,
+ [route('api/orders')]: `import { listOrders } from '@/lib/orders';\nexport async function GET() { return Response.json(await listOrders()); }\n`,
+ 'src/lib/orders.ts': `import { lookup } from './store';\nexport const listOrders = () => lookup('orders');\n`,
+ 'src/lib/store.ts': `import { createClient } from '@supabase/supabase-js';\nconst c = createClient('https://x.supabase.co', 'anon');\nexport const lookup = (t: string) => c.from(t).select();\n`,
+ 'src/lib/prisma.ts': `import { PrismaClient } from '@prisma/client';\nexport const prisma = new PrismaClient();\n`,
+ [route('api/cart')]: `import { cookies } from 'next/headers';\nexport async function GET() { return Response.json({ cart: (await cookies()).get('cart')?.value }); }\n`,
+ [route('api/quote')]: `export async function GET() { const r = await fetch('https://pay.example.com', { headers: { key: process.env.PAYMENT_KEY! } }); return Response.json(await r.json()); }\n`,
+ [route('api/files/[name]')]: `import { readFile } from 'node:fs/promises';\nexport async function GET(_: Request, { params }: { params: { name: string } }) { return new Response(await readFile('uploads/' + params.name)); }\n`,
+ };
+ assert.deepEqual(open(files), ['GET /api/cart', 'GET /api/files/[name]', 'GET /api/orders', 'GET /api/quote', 'GET /api/users']);
+});
+
+test('an import that can\'t be followed could hold anything, so it counts as reading something', () => {
+ assert.deepEqual(open({ [route('api/orders')]: `import { listOrders } from '@/lib/missing';\nexport async function GET() { return Response.json(await listOrders()); }\n` }), ['GET /api/orders']);
+});
+
+test('a public cache header counts in other frameworks too, on the endpoint that sets it', () => {
+ const graph = build({ 'server/routes.js': [
+ `import express from 'express';`, `const router = express.Router();`,
+ `router.get('/api/plans', (req, res) => { res.set('Cache-Control', 'public, max-age=60'); res.json([]); });`,
+ `router.get('/api/books', (req, res) => res.json([]));`,
+ `export default router;`, '',
+ ].join('\n') });
+ assert.deepEqual(openEndpoints(graph), ['GET /api/books']);
+});
+
+test('a static read only applies to Next.js, where one file is one endpoint', () => {
+ const graph = build({ 'server/routes.js': `import express from 'express';\nconst router = express.Router();\nrouter.get('/api/books', (req, res) => res.json([]));\nexport default router;\n` });
+ assert.deepEqual(openEndpoints(graph), ['GET /api/books']);
+});
+
+// ---------- a CMS's own API (#42) ----------
+const PAYLOAD_API = `/* THIS FILE WAS GENERATED AUTOMATICALLY BY PAYLOAD. */\n/* DO NOT MODIFY IT BECAUSE IT COULD BE REWRITTEN AT ANY TIME. */\nimport config from '@payload-config';\nimport { REST_DELETE, REST_GET, REST_PATCH, REST_POST } from '@payloadcms/next/routes';\nexport const GET = REST_GET(config);\nexport const POST = REST_POST(config);\nexport const DELETE = REST_DELETE(config);\nexport const PATCH = REST_PATCH(config);\n`;
+
+test('Payload CMS API routes check access themselves', () => {
+ const graph = build({ [route('(payload)/api/[...slug]')]: PAYLOAD_API, [route('(payload)/api/graphql')]: `import config from '@payload-config';\nimport { GRAPHQL_POST } from '@payloadcms/next/routes';\nexport const POST = GRAPHQL_POST(config);\n` });
+ assert.deepEqual(openEndpoints(graph), []);
+ assert.deepEqual(graph.health.issues.filter((i) => i.kind === 'unprotected-endpoint'), []);
+});
+
+test('a route that only has a variable called payload is not Payload CMS', () => {
+ assert.deepEqual(open({ [route('api/notes')]: `export async function POST(req: Request) { const payload = await req.json(); return Response.json(payload); }\n` }), ['POST /api/notes']);
+});
+
+// ---------- a webhook's "POST only" reply, and how it's locked (#43) ----------
+const LOCKED_POST = (check) => `export async function POST(req: Request) {\n ${check}\n return Response.json({ ok: true });\n}\n`;
+const POST_ONLY = `export async function GET() { return Response.json({ error: 'POST only' }, { status: 405 }); }\n`;
+
+test('a GET that only answers "method not allowed" is not an open endpoint or a fake-events risk', () => {
+ const graph = build({ [route('api/partner/webhook')]: POST_ONLY + LOCKED_POST(`if (!verifyPartnerSignature(req)) return new Response('', { status: 401 });`) });
+ assert.deepEqual(openEndpoints(graph), []);
+ assert.deepEqual(open({ [route('api/items')]: `export const GET = () => new Response(null, { status: 405, headers: { Allow: 'POST' } });\n` }), []);
+});
+
+test('a GET that reads data before answering 405, or a POST-only reply on POST itself, still counts', () => {
+ assert.deepEqual(open({ [route('api/items')]: `import { db } from '@/lib/db';\nexport async function GET() { const rows = await db.item.findMany(); return Response.json(rows, { status: 405 }); }\n` }), ['GET /api/items']);
+ assert.deepEqual(open({ [route('api/items')]: `export async function POST(req: Request) { await req.json(); return Response.json({ ok: true }); }\n${POST_ONLY}` }), ['POST /api/items']);
+});
+
+test('a webhook locked with a shared secret or a helper is not open', () => {
+ const locks = [
+ `if (req.headers.get('authorization') !== \`Bearer \${process.env.PARTNER_SECRET}\`) return new Response('', { status: 200 });`,
+ `if (token !== process.env.PARTNER_TOKEN) return Response.redirect('/');`,
+ `if (!crypto.timingSafeEqual(a, b)) return Response.redirect('/');`,
+ `if (!isAuthorized(req)) return Response.redirect('/');`,
+ `if (!verifyWebhookSecret(req)) return Response.redirect('/');`,
+ ];
+ for (const lock of locks) assert.deepEqual(open({ [route('api/partner/webhook')]: LOCKED_POST(lock) }), [], lock);
+});
+
+test('a webhook that does nothing to check its sender is still reported', () => {
+ assert.deepEqual(open({ [route('api/partner/webhook')]: LOCKED_POST(`const event = await req.json(); console.log(event);`) }), ['POST /api/partner/webhook']);
+ assert.deepEqual(open({ [route('api/partner/webhook')]: LOCKED_POST(`if (process.env.PARTNER_SECRET) console.log('configured');`) }), ['POST /api/partner/webhook']);
+});
+
+// ---------- a browser tracker's site token (#40) ----------
+const SITE_TOKEN = ['a1b2c3d4', 'e5f6a7b8', 'c9d0e1f2'].join('');
+const secrets = (src, p = 'src/components/Widget.tsx') => findIssues(src, { path: p, category: 'code', lang: 'typescript' }).filter((x) => x.k === 'secret');
+
+test('a token handed to a browser tracker script is public by design', () => {
+ const forms = [
+ `export const T = () => <Script src="https://t.example.com/a.js" data-token="${SITE_TOKEN}" />;`,
+ `const SITE_TOKEN = "${SITE_TOKEN}";\nexport const T = () => <Script src="https://t.example.com/a.js" data-site={SITE_TOKEN} />;`,
+ `const token = "${SITE_TOKEN}";\nconst s = document.createElement('script');\ns.src = 'https://t.example.com/a.js';\ns.dataset.site = token;`,
+ `const token = "${SITE_TOKEN}";\nconst s = document.createElement('script');\ns.setAttribute('data-site', token);`,
+ ];
+ for (const src of forms) assert.deepEqual(secrets(src), [], src);
+ // the file says what it is, and the script tag takes the token some other way
+ assert.deepEqual(secrets(`const TRACKER_TOKEN = "${SITE_TOKEN}";\nexport const A = () => <Script src={\`https://t.example.com/a.js?id=\${TRACKER_TOKEN}\`} />;`, 'src/components/SiteAnalytics.tsx'), []);
+});
+
+test('a token near a script tag but not given to it, or a secret by name, is still flagged', () => {
+ const same = 'const SITE_TOKEN = "' + SITE_TOKEN + '";\n';
+ assert.equal(secrets(`${same}fetch('/x', { headers: { t: SITE_TOKEN } });\nexport const T = () => <Script src="https://t.example.com/a.js" />;`).length, 1);
+ assert.equal(secrets(`${same}export const T = () => <div data-site={SITE_TOKEN} />;`).length, 1);
+ assert.equal(secrets(`const SITE_TOKEN = "${SITE_TOKEN}";\nexport const send = () => fetch('/x', { headers: { t: SITE_TOKEN } });`, 'src/components/SiteAnalytics.tsx').length, 1);
+ for (const name of ['API_SECRET', 'ACCESS_TOKEN', 'AUTH_TOKEN', 'REFRESH_TOKEN', 'PRIVATE_KEY']) {
+ assert.equal(secrets(`const ${name} = "${SITE_TOKEN}";\nexport const T = () => <Script src="https://t.example.com/a.js" data-site={${name}} />;`, 'src/components/SiteAnalytics.tsx').length, 1, name);
+ }
+});
+
+// ---------- files a tool opens by name (#50) ----------
+const unused = (files) => build(files).health.issues.filter((i) => i.kind === 'unused-file').flatMap((i) => i.items);
+
+test('a file whose comment says a tool opens it, or that it is generated, is not unused', () => {
+ const heads = [
+ '// The CLI reads this file directly.', '/* This file is loaded by the migration runner at startup. */', '/**\n * Used by the tool: it opens this file by name.\n */',
+ '# This file is read by the deploy script.', '/* THIS FILE WAS GENERATED AUTOMATICALLY. */', '// Do not delete: the build picks up this file at runtime.',
+ ];
+ heads.forEach((head) => assert.deepEqual(unused({ 'src/content/leftover.ts': `${head}\nexport const x = 1;\n` }), [], head));
+});
+
+test('a plain orphan, or one that only mentions those words in passing, still looks unused', () => {
+ const found = ['// Reads the config file and returns it.', '// TODO: wire this into the CLI', `const s = 'The CLI reads this file directly';`, '/**\n * Create a record with an auto-generated id.\n */', '/** Do not modify the input array. */', '// Generated by the form, this value is trimmed.'];
+ found.forEach((head) => assert.deepEqual(unused({ 'src/content/leftover.ts': `${head}\nexport const x = 1;\n` }), ['f:src/content/leftover.ts'], head));
+});