@apideck/quickbooks-review-check 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apideck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# quickbooks-review-check
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Free, open-source self-check for the Intuit QuickBooks Online app security review.** Run it before you submit, and on every deploy after you're listed, so the annual re-review doesn't catch you out.
+
+It does two kinds of checks, both free:
+
+| | What it checks | How |
+|---|---|---|
+| **Runtime** | HTTPS enforcement, TLS 1.0/1.1/1.2/1.3, certificate, HSTS, `Cache-Control: no-store` (not `private`) on sensitive pages, TRACE/TRACK disabled, `Secure` + `HttpOnly` session cookies, the **302 rule** on your OAuth callback, open redirects, version-banner disclosure, browser security headers | Probes your deployed app from outside |
+| **Source** | Refresh token **and realmId** encrypted at rest (AES/3DES), AES key not inline, tokens or `authResponse` logged, tokens sent to the browser / `localStorage`, hardcoded `state: 'testState'` (CSRF in Intuit's sample code), missing state validation, CSRF middleware, TLS verification disabled, weak ciphers (ECB, `createCipher`), SQL/QBO-query string interpolation, XSS sinks, XXE, QuickBooks data flowing into LLM/analytics/APM SDKs | Static scan of your repo (JS/TS, Python, Ruby, PHP, Java, C#, Go). No code leaves your machine. |
+
+Every result maps to one of Intuit's review categories. Each report ends with a **manual attestation checklist** for the items no scanner can prove: patching, access control, DAST, and the data-usage rules.
+
+> **Disclaimer.** This is a self-assessment aid, not a certification, penetration test, security audit or legal/compliance advice. Passing these checks does not mean an app meets Intuit's requirements or will be approved. Always confirm requirements against Intuit's official developer documentation. Only run runtime checks against apps you own or are authorized to test. Provided "as is" under the MIT License, without warranty.
+>
+> Not affiliated with, endorsed by or sponsored by Intuit Inc. Intuit and QuickBooks are trademarks of Intuit Inc., used only to describe what the tool checks against.
+
+## Quick start
+
+```bash
+npx @apideck/quickbooks-review-check \
+  --url https://app.example.com \
+  --callback /oauth/quickbooks/callback \
+  --path /dashboard --path /settings/quickbooks \
+  --header "Cookie: session=…" \
+  --source .
+```
+
+- `--callback` is the Redirect URI you registered with Intuit. The tool calls it with a fake `code`, `state` and `realmId`, and checks that it answers with a `302`, not HTML.
+- `--path` names sensitive pages that must send `no-store`. Pass a session cookie with `--header` so they're checked while signed in, not as a redirect to the login page.
+- `--markdown report.md` and `--json report.json` write reports. `--fail-on warn|fail|never` controls the exit code.
+
+## GitHub Action
+
+```yaml
+name: QuickBooks review check
+on:
+  deployment_status:
+  schedule: [{ cron: '0 6 * * 1' }]   # weekly, catches drift before Intuit's annual re-review
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: apideck-libraries/quickbooks-review-check@v0
+        with:
+          url: https://app.example.com
+          callback: /oauth/quickbooks/callback
+          paths: |
+            /dashboard
+            /settings/quickbooks
+          headers: |
+            Cookie: ${{ secrets.QBRC_SESSION_COOKIE }}
+          source: .
+          fail-on: fail
+```
+
+The Markdown report is written to the job summary. To scan source only (e.g. on pull requests), omit `url`.
+
+## Encrypting the refresh token (Node)
+
+Intuit requires the refresh token and realmId to be encrypted with AES (preferred) or 3DES, with the key kept out of your code:
+
+```js
+import crypto from 'node:crypto';
+const key = Buffer.from(process.env.TOKEN_ENCRYPTION_KEY, 'base64'); // 32 bytes: `openssl rand -base64 32`
+
+export function encrypt(plain) {
+  const iv = crypto.randomBytes(12);
+  const c = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const data = Buffer.concat([c.update(plain, 'utf8'), c.final()]);
+  return Buffer.concat([iv, c.getAuthTag(), data]).toString('base64');
+}
+
+export function decrypt(blob) {
+  const buf = Buffer.from(blob, 'base64');
+  const d = crypto.createDecipheriv('aes-256-gcm', key, buf.subarray(0, 12));
+  d.setAuthTag(buf.subarray(12, 28));
+  return Buffer.concat([d.update(buf.subarray(28)), d.final()]).toString('utf8');
+}
+```
+
+## Using Apideck?
+
+If your app connects to QuickBooks through [Apideck Vault](https://www.apideck.com), Apideck stores and encrypts the Intuit OAuth tokens and realmId. Your app never holds them, and the scanner recognizes this setup. Ask Apideck for its security documentation if your reviewer wants details on token storage. You still own the runtime checks (HTTPS, cookies, cache headers) and the data-usage rules for your app, and this tool covers those.
+
+## Sample apps
+
+`examples/insecure-app` and `examples/secure-app` are two small QuickBooks apps (Node built-ins only) that the end-to-end test runs over real TLS:
+
+- **insecure-app** does what many apps start with: Intuit's sample OAuth code with `state: 'testState'`, tokens logged and stored in plain text, an HTML callback page, TRACE echoed, TLS 1.0 accepted, `Cache-Control: private`, cookies without flags, an open redirect and plain HTTP. **Never deploy it.**
+- **secure-app** fixes every one of those.
+
+```bash
+eval "$(node examples/certs.js)" && export TLS_KEY TLS_CERT NODE_EXTRA_CA_CERTS
+node examples/insecure-app/server.js &   # https://localhost:8443, http://localhost:8080
+node bin/quickbooks-review-check.js --url https://localhost:8443 --http-port 8080 --callback /oauth/callback --path /dashboard --source examples/insecure-app
+```
+
+`node examples/record.js <dir>` re-records both apps' scan results and source files for the website's "Try a sample" buttons.
+
+## Development
+
+```bash
+npm test          # node:test, zero dependencies
+node bin/quickbooks-review-check.js --source test/fixtures/insecure --fail-on never
+```
+
+MIT © Apideck

package/bin/quickbooks-review-check.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+// exitCode rather than process.exit(), so piped stdout (e.g. `--json - | jq`) is fully flushed.
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (err) => {
+    console.error(err);
+    process.exitCode = 2;
+  },
+);

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@apideck/quickbooks-review-check",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Free self-check for the Intuit QuickBooks Online app security review: runtime probes + source scan, as a CLI and GitHub Action.",
+  "type": "module",
+  "bin": {
+    "quickbooks-review-check": "bin/quickbooks-review-check.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "quickbooks",
+    "intuit",
+    "security",
+    "app-review",
+    "oauth",
+    "github-action"
+  ],
+  "author": "Apideck",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apideck-libraries/quickbooks-review-check.git"
+  },
+  "homepage": "https://www.apideck.com/tools/quickbooks-review"
+}

package/src/cli.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import { parseArgs } from 'node:util';
+import { runRuntime } from './runtime.js';
+import { scanSource } from './source.js';
+import { toConsole, toMarkdown, toJson, summarize } from './report.js';
+
+const HELP = `quickbooks-review-check — free self-check for the Intuit QuickBooks Online app security review
+
+Usage:
+  quickbooks-review-check --url https://app.example.com --callback /oauth/callback [--source .]
+  quickbooks-review-check --source ./my-app
+
+Runtime checks (probe your deployed app):
+  --url <url>            Base URL of your deployed app
+  --callback <path>      OAuth redirect URI path (checks the 302 rule, cache headers, cookies)
+  --path <path>          Sensitive page to check for no-store caching (repeatable)
+  --header "K: V"        Extra request header, e.g. an authenticated session cookie (repeatable)
+  --timeout <ms>         Per-request timeout (default 10000)
+  --http-port <port>     Port for the plain-HTTP redirect check (default 80; for local testing)
+
+Source checks (static scan of your code):
+  --source <dir>         Scan a repository for token-handling issues
+  --include-tests        Also scan test/example files
+
+Output:
+  --markdown <file>      Write a Markdown report ("-" for stdout)
+  --json <file>          Write a JSON report ("-" for stdout)
+  --fail-on <level>      Exit 1 on: fail (default) | warn | never
+  -q, --quiet            Don't print the console report
+  -h, --help
+`;
+
+export async function main(argv) {
+  let args;
+  try {
+    ({ values: args } = parseArgs({
+      args: argv,
+      options: {
+        url: { type: 'string' },
+        callback: { type: 'string' },
+        path: { type: 'string', multiple: true, default: [] },
+        header: { type: 'string', multiple: true, default: [] },
+        timeout: { type: 'string', default: '10000' },
+        'http-port': { type: 'string' },
+        source: { type: 'string' },
+        'include-tests': { type: 'boolean', default: false },
+        markdown: { type: 'string' },
+        json: { type: 'string' },
+        'fail-on': { type: 'string', default: 'fail' },
+        quiet: { type: 'boolean', short: 'q', default: false },
+        verbose: { type: 'boolean', short: 'v', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+    }));
+  } catch (e) {
+    console.error(`${e.message}\n\n${HELP}`);
+    return 2;
+  }
+  if (args.help || (!args.url && !args.source)) {
+    console.log(HELP);
+    return args.help ? 0 : 2;
+  }
+
+  const headers = {};
+  for (const h of args.header) {
+    const i = h.indexOf(':');
+    if (i > 0) headers[h.slice(0, i).trim().toLowerCase()] = h.slice(i + 1).trim();
+  }
+  const log = args.verbose ? (m) => console.error(`· ${m}`) : () => {};
+
+  const results = [];
+  if (args.url) {
+    const url = /^https?:\/\//.test(args.url) ? args.url : `https://${args.url}`;
+    results.push(...(await runRuntime({ url, paths: args.path, callback: args.callback, headers, timeout: Number(args.timeout), log, httpPort: args['http-port'] ? Number(args['http-port']) : undefined })));
+  }
+  if (args.source) {
+    const { results: src, scanned } = scanSource(args.source, { includeTests: args['include-tests'] });
+    log(`scanned ${scanned} files`);
+    results.push(...src);
+  }
+
+  const report = { target: args.url, source: args.source, results };
+  if (!args.quiet) console.log(toConsole(report));
+  writeOut(args.markdown, () => toMarkdown(report));
+  writeOut(args.json, () => toJson(report));
+  if (process.env.GITHUB_STEP_SUMMARY) fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${toMarkdown(report)}\n`);
+
+  const c = summarize(results);
+  if (args['fail-on'] === 'never') return 0;
+  if (c.fail || (args['fail-on'] === 'warn' && c.warn)) return 1;
+  return 0;
+}
+
+function writeOut(dest, render) {
+  if (!dest) return;
+  if (dest === '-') process.stdout.write(`${render()}\n`);
+  else fs.writeFileSync(dest, render());
+}

package/src/guard.js

@@ -0,0 +1,75 @@
+import dns from 'node:dns';
+import net from 'node:net';
+
+// SSRF guard for running runtime checks as a hosted service: only public hosts on standard ports,
+// and every connection resolves through a lookup that re-checks the IP (defeats DNS rebinding).
+
+const V4_BLOCKED = [
+  ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16],
+  ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24], ['192.88.99.0', 24], ['192.168.0.0', 16],
+  ['198.18.0.0', 15], ['198.51.100.0', 24], ['203.0.113.0', 24], ['224.0.0.0', 4], ['240.0.0.0', 4],
+];
+
+const v4ToInt = (ip) => ip.split('.').reduce((n, o) => (n << 8) + Number(o), 0) >>> 0;
+
+export function isPublicIp(ip) {
+  if (net.isIPv4(ip)) {
+    const n = v4ToInt(ip);
+    return !V4_BLOCKED.some(([base, bits]) => (n >>> (32 - bits)) === (v4ToInt(base) >>> (32 - bits)));
+  }
+  if (net.isIPv6(ip)) {
+    const lower = ip.toLowerCase();
+    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(lower);
+    if (mapped) return isPublicIp(mapped[1]);
+    if (lower === '::' || lower === '::1') return false;
+    // fc00::/7 unique-local, fe80::/10 link-local, ff00::/8 multicast, 2001:db8::/32 docs, 64:ff9b::/96 NAT64
+    return !/^(f[cd]|fe[89ab]|ff|2001:db8|64:ff9b)/.test(lower);
+  }
+  return false;
+}
+
+export class TargetError extends Error {}
+
+export function validateTarget(raw) {
+  let u;
+  try {
+    u = new URL(/^https?:\/\//i.test(raw) ? raw : `https://${raw}`);
+  } catch {
+    throw new TargetError('Enter a valid URL, like https://app.example.com');
+  }
+  if (!['http:', 'https:'].includes(u.protocol)) throw new TargetError('Only http and https URLs can be checked.');
+  if (u.username || u.password) throw new TargetError('Remove credentials from the URL.');
+  if (u.port && !['80', '443'].includes(u.port)) throw new TargetError('The hosted scanner only checks standard ports (80/443). Use the CLI for other ports.');
+  const host = u.hostname.replace(/^\[|\]$/g, '');
+  if (net.isIP(host) && !isPublicIp(host)) throw new TargetError('Private and reserved IP addresses cannot be scanned.');
+  if (/^(localhost|.*\.localhost|.*\.local|.*\.internal|.*\.lan|.*\.home\.arpa)$/i.test(host) || !host.includes('.')) {
+    throw new TargetError('Internal hostnames cannot be scanned. Use the CLI inside your network instead.');
+  }
+  u.hash = '';
+  return u;
+}
+
+// dns.lookup-compatible function that refuses non-public answers.
+export function safeLookup(hostname, options, callback) {
+  if (typeof options === 'function') {
+    callback = options;
+    options = {};
+  }
+  dns.lookup(hostname, { ...options, all: true }, (err, addresses) => {
+    if (err) return callback(err);
+    const bad = addresses.find((a) => !isPublicIp(a.address));
+    if (bad || !addresses.length) {
+      const e = new Error(`${hostname} resolves to a non-public address`);
+      e.code = 'EBLOCKED';
+      return callback(e);
+    }
+    if (options.all) return callback(null, addresses);
+    callback(null, addresses[0].address, addresses[0].family);
+  });
+}
+
+export function assertPublicHost(hostname) {
+  return new Promise((resolve, reject) => {
+    safeLookup(hostname, { all: true }, (err, addrs) => (err ? reject(new TargetError(err.code === 'EBLOCKED' ? 'That host resolves to a private address and cannot be scanned.' : `Could not resolve ${hostname}.`)) : resolve(addrs)));
+  });
+}

package/src/http.js

@@ -0,0 +1,111 @@
+import http from 'node:http';
+import https from 'node:https';
+import tls from 'node:tls';
+
+const BODY_LIMIT = 64 * 1024;
+
+// Low-level request that never follows redirects and supports any method (fetch rejects TRACE).
+export function request(url, { method = 'GET', headers = {}, timeout = 10000, insecure = false, lookup } = {}) {
+  const u = new URL(url);
+  const mod = u.protocol === 'http:' ? http : https;
+  return new Promise((resolve, reject) => {
+    const req = mod.request(
+      u,
+      {
+        method,
+        headers: { 'user-agent': 'quickbooks-review-check/0.1 (+https://github.com/apideck-libraries/quickbooks-review-check)', ...headers },
+        timeout,
+        rejectUnauthorized: !insecure,
+        ...(lookup && { lookup }),
+      },
+      (res) => {
+        const chunks = [];
+        let size = 0;
+        res.on('data', (c) => {
+          if (size < BODY_LIMIT) chunks.push(c);
+          size += c.length;
+        });
+        res.on('end', () => {
+          const raw = res.headers['set-cookie'] || [];
+          resolve({
+            url,
+            status: res.statusCode,
+            headers: res.headers,
+            setCookies: Array.isArray(raw) ? raw : [raw],
+            body: Buffer.concat(chunks).toString('utf8').slice(0, BODY_LIMIT),
+          });
+        });
+        res.on('error', reject);
+      },
+    );
+    req.on('timeout', () => req.destroy(new Error(`timeout after ${timeout}ms`)));
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+// Try a TLS handshake pinned to one protocol version. Resolves { ok, protocol, cipher } or { ok:false, error }.
+// SECLEVEL=0 lets modern OpenSSL builds still *offer* TLS 1.0/1.1 so we can detect servers that accept them.
+export function tlsHandshake(host, port, version, { timeout = 8000, lookup } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => {
+      if (!settled) {
+        settled = true;
+        resolve(v);
+      }
+    };
+    let socket;
+    try {
+      socket = tls.connect({
+        host,
+        port,
+        servername: host,
+        minVersion: version,
+        maxVersion: version,
+        ciphers: version === 'TLSv1.3' ? undefined : 'DEFAULT:@SECLEVEL=0',
+        rejectUnauthorized: false,
+        timeout,
+        ...(lookup && { lookup }),
+      });
+    } catch (e) {
+      return done({ ok: false, error: e.message, clientUnsupported: true });
+    }
+    socket.once('secureConnect', () => {
+      const res = { ok: true, protocol: socket.getProtocol(), cipher: socket.getCipher(), authorized: socket.authorized, authError: socket.authorizationError };
+      socket.end();
+      done(res);
+    });
+    socket.once('timeout', () => {
+      socket.destroy();
+      done({ ok: false, error: 'timeout' });
+    });
+    socket.once('error', (e) => {
+      // A client-side "no protocols available" means this Node/OpenSSL build cannot test the version.
+      const clientUnsupported = /no protocols available|unsupported protocol/i.test(e.message) && !/alert/i.test(e.message);
+      done({ ok: false, error: e.message, clientUnsupported });
+    });
+  });
+}
+
+// Parse a Set-Cookie header into { name, attrs: Set<lowercase attr names>, sameSite }.
+export function parseSetCookie(header) {
+  const parts = header.split(';').map((p) => p.trim());
+  const [nameValue, ...attrs] = parts;
+  const name = nameValue.split('=')[0].trim();
+  const attrNames = new Set();
+  let sameSite = null;
+  for (const a of attrs) {
+    const [k, v] = a.split('=');
+    const key = k.trim().toLowerCase();
+    attrNames.add(key);
+    if (key === 'samesite') sameSite = (v || '').trim().toLowerCase();
+  }
+  return { name, attrs: attrNames, sameSite, raw: header };
+}
+
+export function isHtml(res) {
+  const ct = String(res.headers['content-type'] || '').toLowerCase();
+  if (ct.includes('text/html') || ct.includes('application/xhtml')) return res.body.trim().length > 0;
+  return /^\s*(<!doctype html|<html)/i.test(res.body);
+}

package/src/report.js

@@ -0,0 +1,78 @@
+import { CATEGORIES, REQUIREMENTS, MANUAL_CHECKS } from './requirements.js';
+
+const ICON = { pass: '✅', fail: '❌', warn: '⚠️', info: 'ℹ️', skip: '⏭️' };
+const ORDER = { fail: 0, warn: 1, pass: 2, info: 3, skip: 4 };
+
+export function summarize(results) {
+  const counts = { pass: 0, fail: 0, warn: 0, info: 0, skip: 0 };
+  for (const r of results) counts[r.status]++;
+  return counts;
+}
+
+function grouped(results) {
+  const byCat = new Map(Object.keys(CATEGORIES).map((c) => [c, []]));
+  for (const r of results) byCat.get(REQUIREMENTS[r.requirement]?.category || 'transport').push(r);
+  for (const list of byCat.values()) list.sort((a, b) => ORDER[a.status] - ORDER[b.status]);
+  return byCat;
+}
+
+export function toJson({ target, source, results }) {
+  return JSON.stringify({ tool: 'quickbooks-review-check', version: '0.1.0', generatedAt: new Date().toISOString(), target, source, summary: summarize(results), results, manualChecks: MANUAL_CHECKS.map((m) => ({ ...m, requirement: REQUIREMENTS[m.id].title })) }, null, 2);
+}
+
+export function toMarkdown({ target, source, results }) {
+  const c = summarize(results);
+  const verdict = c.fail ? `❌ **${c.fail} blocking issue${c.fail > 1 ? 's' : ''}** — Intuit would likely send this back.` : c.warn ? '⚠️ **No blocking issues**, but review the warnings before submitting.' : '✅ **All automated checks passed.**';
+  const lines = [
+    '# QuickBooks App Security Review — self-check',
+    '',
+    [target && `**App:** ${target}`, source && `**Source:** \`${source}\``].filter(Boolean).join(' · '),
+    '',
+    verdict,
+    '',
+    `| ✅ Pass | ❌ Fail | ⚠️ Warn | ⏭️ Skipped |`,
+    `|---|---|---|---|`,
+    `| ${c.pass} | ${c.fail} | ${c.warn} | ${c.skip} |`,
+    '',
+  ];
+  for (const [cat, list] of grouped(results)) {
+    if (!list.length) continue;
+    lines.push(`## ${CATEGORIES[cat]}`, '');
+    for (const r of list) {
+      lines.push(`- ${ICON[r.status]} **${r.title}** — ${md(r.detail)}`);
+      if (r.fix && (r.status === 'fail' || r.status === 'warn')) lines.push(`  - _Fix:_ ${r.fix}`);
+      for (const l of r.locations || []) lines.push(`  - \`${l.file}:${l.line}\` ${l.snippet ? `— \`${l.snippet.replace(/`/g, "'")}\`` : ''}`);
+    }
+    lines.push('');
+  }
+  lines.push('## Manual attestation (Intuit will ask)', '', 'These cannot be proven by a scanner. Tick them off before you submit:', '');
+  for (const m of MANUAL_CHECKS) lines.push(`- [ ] ${m.prompt}`);
+  lines.push('', '---', '_Generated by [quickbooks-review-check](https://github.com/apideck-libraries/quickbooks-review-check), a free tool from [Apideck](https://www.apideck.com). Self-assessment aid only, provided as is. Not affiliated with or endorsed by Intuit Inc.; results do not guarantee approval. QuickBooks is a trademark of Intuit Inc._');
+  return lines.join('\n');
+}
+
+const md = (s) => String(s || '').replace(/\|/g, '\\|');
+
+const color = (code) => (s) => (process.stdout.isTTY && !process.env.NO_COLOR ? `\x1b[${code}m${s}\x1b[0m` : s);
+const C = { pass: color(32), fail: color(31), warn: color(33), info: color(36), skip: color(90), bold: color(1), dim: color(90) };
+const TAG = { pass: 'PASS', fail: 'FAIL', warn: 'WARN', info: 'INFO', skip: 'SKIP' };
+
+export function toConsole({ target, source, results }) {
+  const out = [C.bold('QuickBooks App Security Review — self-check'), C.dim([target, source].filter(Boolean).join('  ·  ')), ''];
+  for (const [cat, list] of grouped(results)) {
+    if (!list.length) continue;
+    out.push(C.bold(CATEGORIES[cat]));
+    for (const r of list) {
+      out.push(`  ${C[r.status](TAG[r.status].padEnd(4))}  ${r.title}`);
+      if (r.status !== 'pass') out.push(C.dim(`        ${r.detail}`));
+      if (r.fix && (r.status === 'fail' || r.status === 'warn')) out.push(`        → ${r.fix}`);
+      for (const l of (r.locations || []).slice(0, 5)) out.push(C.dim(`        ${l.file}:${l.line}  ${l.snippet || ''}`));
+      if ((r.locations || []).length > 5) out.push(C.dim(`        … ${r.locations.length - 5} more`));
+    }
+    out.push('');
+  }
+  const c = summarize(results);
+  out.push(`${C.pass(`${c.pass} passed`)}  ${C.fail(`${c.fail} failed`)}  ${C.warn(`${c.warn} warnings`)}  ${C.skip(`${c.skip} skipped`)}`);
+  out.push(C.dim(`Plus ${MANUAL_CHECKS.length} manual attestation items — run with --markdown to get the checklist.`));
+  return out.join('\n');
+}

package/src/requirements.js

@@ -0,0 +1,111 @@
+// Catalog of Intuit QuickBooks Online app security-review requirements.
+// Each automated check references one of these ids so reports group by Intuit's categories.
+// Source: Intuit Developer "Security requirements" for publishing an app (paraphrased).
+
+export const CATEGORIES = {
+  transport: 'Server & transport',
+  attacks: 'Attack vulnerabilities',
+  cookies: 'Cookies & sessions',
+  oauth: 'OAuth token management',
+  redirect: 'Token-endpoint redirect rule',
+  data: 'QuickBooks data usage',
+};
+
+export const REQUIREMENTS = {
+  'https-everywhere': {
+    category: 'transport',
+    title: 'HTTPS enforced on every page',
+    text: 'All pages of the app must be served over HTTPS.',
+  },
+  'tls-version': {
+    category: 'transport',
+    title: 'TLS 1.1 minimum, TLS 1.2+ recommended',
+    text: 'SSL must support TLS 1.1 or higher; TLS 1.2 with AES-256 and SHA-256 is recommended.',
+  },
+  'cache-control': {
+    category: 'transport',
+    title: 'Caching disabled on sensitive pages',
+    text: 'Use Cache-Control no-cache and no-store (not private) on SSL and sensitive pages.',
+  },
+  'http-methods': {
+    category: 'transport',
+    title: 'TRACE and unused HTTP methods disabled',
+    text: 'The web server must disable TRACE and other HTTP methods that are not used.',
+  },
+  'patching-logging': {
+    category: 'transport',
+    title: 'Patches current; no credential or QuickBooks data logging',
+    text: 'OS, web server and app server patches must be current. Never log user credentials or QuickBooks data.',
+  },
+  csrf: {
+    category: 'attacks',
+    title: 'Cross-Site Request Forgery protection',
+    text: 'State-changing requests (including the OAuth flow) must be protected against CSRF.',
+  },
+  xss: {
+    category: 'attacks',
+    title: 'Cross-Site Scripting (reflected & stored)',
+    text: 'Validate input and encode output to prevent reflected and stored XSS.',
+  },
+  injection: {
+    category: 'attacks',
+    title: 'SQL and XML injection',
+    text: 'Use parameterized queries and safe XML parsing.',
+  },
+  'auth-session': {
+    category: 'attacks',
+    title: 'Authentication, session management, access control',
+    text: 'Authentication, session management and functional-level access control must be robust.',
+  },
+  'open-redirect': {
+    category: 'attacks',
+    title: 'Validated forwards and redirects',
+    text: 'Redirect logic must be validated so it cannot be abused as an open redirect.',
+  },
+  'cookie-flags': {
+    category: 'cookies',
+    title: 'Secure and HttpOnly on session cookies',
+    text: 'All session cookies must set the Secure and HttpOnly attributes.',
+  },
+  'token-exposure': {
+    category: 'oauth',
+    title: 'Tokens never exposed or shared',
+    text: 'Intuit OAuth tokens and customer-identifying information must not be exposed in the app or shared with other parties.',
+  },
+  'token-encryption': {
+    category: 'oauth',
+    title: 'Refresh token and realmId encrypted at rest',
+    text: 'Refresh token and realmId must be encrypted (AES preferred, or 3DES) and stored in persistent storage.',
+  },
+  'key-storage': {
+    category: 'oauth',
+    title: 'Encryption key kept in separate configuration',
+    text: 'The AES key must be stored in a separate configuration file, not inline in code.',
+  },
+  'token-endpoint-302': {
+    category: 'redirect',
+    title: 'Token-bearing endpoints respond with 302, not HTML',
+    text: 'Endpoints receiving tokens or sensitive data in URL parameters must not return HTML; they should 302 redirect to avoid Referer leaks.',
+  },
+  'no-third-party-access': {
+    category: 'data',
+    title: 'No third-party access to QuickBooks data',
+    text: 'The app must not give third parties access to customer QuickBooks data, via APIs or any other means.',
+  },
+  'data-minimization': {
+    category: 'data',
+    title: 'Store QuickBooks data only for functional use',
+    text: 'Do not export, save or store QuickBooks data for any purpose other than the functional use of the app.',
+  },
+};
+
+// Items no scanner can prove. These are printed as an attestation checklist in every report.
+export const MANUAL_CHECKS = [
+  { id: 'patching-logging', prompt: 'OS, web server, runtime and dependencies are on current patch levels (e.g. `npm audit`, Dependabot, base image updates).' },
+  { id: 'auth-session', prompt: 'Every route that reads or writes QuickBooks data enforces authentication and checks the user owns that realmId (no IDOR).' },
+  { id: 'xss', prompt: 'A penetration test or DAST scan of signed-in pages (e.g. Aikido AI pentesting or an OWASP ZAP baseline) shows no XSS, CSRF, injection or access-control issues.' },
+  { id: 'injection', prompt: 'All database and XML access is parameterized; XML parsers have external entities disabled.' },
+  { id: 'no-third-party-access', prompt: 'No QuickBooks data is sent to analytics, LLM, logging or other third-party services outside the app\'s stated function.' },
+  { id: 'data-minimization', prompt: 'QuickBooks data is retained only as long as needed for the app\'s function, and deleted on disconnect.' },
+  { id: 'token-exposure', prompt: 'Disconnect/revoke flow calls Intuit\'s revoke endpoint and deletes stored tokens.' },
+];

package/src/runtime.js

@@ -0,0 +1,301 @@
+import { request, tlsHandshake, parseSetCookie, isHtml } from './http.js';
+
+const SESSION_COOKIE = /(sess|sid|auth|token|jwt|login|remember|connect\.sid|csrf|xsrf|identity|user)/i;
+const EVIL = 'https://evil.example.com/qbrc';
+const REDIRECT_PARAMS = ['redirect', 'redirect_uri', 'redirectUrl', 'next', 'returnTo', 'return_to', 'url', 'continue', 'dest'];
+
+const r = (id, requirement, status, title, detail, extra = {}) => ({ id, requirement, status, title, detail, ...extra });
+
+// ---------- pure analyzers (unit tested) ----------
+
+export function analyzeHttpToHttps(outcome) {
+  const req = 'https-everywhere';
+  if (outcome.error) {
+    return r('http-redirect', req, 'pass', 'Plain HTTP not served', `Port 80 refused or unreachable (${outcome.error}); no plaintext content served.`);
+  }
+  const loc = String(outcome.headers.location || '');
+  if (outcome.status >= 300 && outcome.status < 400 && loc.startsWith('https://')) {
+    const permanent = [301, 308].includes(outcome.status);
+    return r('http-redirect', req, permanent ? 'pass' : 'warn', 'HTTP redirects to HTTPS',
+      permanent ? `HTTP ${outcome.status} → ${loc}` : `HTTP ${outcome.status} → ${loc}. Prefer a permanent 301/308 redirect.`);
+  }
+  return r('http-redirect', req, 'fail', 'HTTP does not redirect to HTTPS',
+    `GET ${outcome.url} returned ${outcome.status}${loc ? ` → ${loc}` : ''}. Every page must be served over HTTPS.`,
+    { fix: 'Redirect all port-80 traffic to HTTPS with a 301 and enable HSTS.' });
+}
+
+// Takes every HTTPS response from the host: an API host often answers `/` from its gateway (a bare
+// 403 without app headers) while the app's own routes do send HSTS.
+export function analyzeHsts(responses) {
+  const list = Array.isArray(responses) ? responses : [responses];
+  const withHsts = list.find((res) => res.headers['strict-transport-security']);
+  if (!withHsts) {
+    const urls = list.map((res) => new URL(res.url).pathname).join(', ');
+    return r('hsts', 'https-everywhere', 'warn', 'No Strict-Transport-Security header', `None of the probed responses (${urls}) set HSTS. Not an explicit Intuit item, but reviewers' scanners flag it.`, { fix: 'Add `Strict-Transport-Security: max-age=31536000; includeSubDomains`.' });
+  }
+  const h = withHsts.headers['strict-transport-security'];
+  const m = /max-age=(\d+)/i.exec(h);
+  if (!m || Number(m[1]) < 15552000) return r('hsts', 'https-everywhere', 'warn', 'HSTS max-age is short', `HSTS: ${h} (recommend ≥ 6 months).`);
+  return r('hsts', 'https-everywhere', 'pass', 'HSTS enabled', `${h} (on ${new URL(withHsts.url).pathname})`);
+}
+
+export function analyzeTls(results) {
+  const out = [];
+  const req = 'tls-version';
+  const { v10, v11, v12, v13 } = results;
+  if (v10?.ok) out.push(r('tls-1.0', req, 'fail', 'TLS 1.0 accepted', 'The server negotiates TLS 1.0, which is below Intuit\'s TLS 1.1 minimum.', { fix: 'Disable TLS 1.0 (and 1.1) on your load balancer / CDN.' }));
+  else if (v10?.clientUnsupported) out.push(r('tls-1.0', req, 'skip', 'TLS 1.0 not testable', 'This Node/OpenSSL build cannot offer TLS 1.0.'));
+  else out.push(r('tls-1.0', req, 'pass', 'TLS 1.0 rejected', v10?.error || 'Handshake refused.'));
+
+  if (v11?.ok) out.push(r('tls-1.1', req, 'warn', 'TLS 1.1 accepted', 'TLS 1.1 meets Intuit\'s minimum but is deprecated; Intuit recommends TLS 1.2+.', { fix: 'Set the minimum protocol to TLS 1.2.' }));
+  else if (v11?.clientUnsupported) out.push(r('tls-1.1', req, 'skip', 'TLS 1.1 not testable', 'This Node/OpenSSL build cannot offer TLS 1.1.'));
+  else out.push(r('tls-1.1', req, 'pass', 'TLS 1.1 rejected', v11?.error || 'Handshake refused.'));
+
+  if (!v12?.ok && !v13?.ok) {
+    out.push(r('tls-modern', req, 'fail', 'No TLS 1.2/1.3 support', `TLS 1.2: ${v12?.error}; TLS 1.3: ${v13?.error}`));
+  } else {
+    const best = v13?.ok ? v13 : v12;
+    const cipher = v12?.ok ? v12.cipher?.name : best.cipher?.name;
+    const strong = !v12?.ok || /AES_?256|AES256|CHACHA20/i.test(cipher || '');
+    out.push(r('tls-modern', req, strong ? 'pass' : 'warn', `${[v12?.ok && 'TLS 1.2', v13?.ok && 'TLS 1.3'].filter(Boolean).join(' + ')} supported`,
+      `Negotiated cipher (TLS 1.2): ${cipher || 'n/a'}${strong ? '' : ' — Intuit recommends AES-256 with SHA-256.'}`));
+    if (best.authorized === false) out.push(r('tls-cert', req, 'fail', 'Certificate not trusted', `Certificate validation failed: ${best.authError}`));
+    else out.push(r('tls-cert', req, 'pass', 'Certificate trusted', 'Certificate chain validates against the system trust store.'));
+  }
+  return out;
+}
+
+export function analyzeCacheControl(res, { sensitive = true } = {}) {
+  const req = 'cache-control';
+  const id = `cache-control:${new URL(res.url).pathname}`;
+  const cc = String(res.headers['cache-control'] || '').toLowerCase();
+  const pragma = String(res.headers.pragma || '').toLowerCase();
+  const dirs = new Set(cc.split(',').map((d) => d.trim().split('=')[0]).filter(Boolean));
+  const path = new URL(res.url).pathname;
+  if (res.status >= 300 && res.status < 400 && !cc) {
+    return r(id, req, 'warn', `Cache-Control not checked on ${path}`, `${path} returned ${res.status} (redirect, probably to login). Pass --header "Cookie: …" to probe it authenticated.`);
+  }
+  if (dirs.has('no-store') && dirs.has('no-cache')) return r(id, req, 'pass', `Caching disabled on ${path}`, `Cache-Control: ${cc}`);
+  if (dirs.has('no-store')) return r(id, req, 'pass', `Caching disabled on ${path}`, `Cache-Control: ${cc} (Intuit asks for both no-store and no-cache; adding no-cache is harmless).`);
+  const status = sensitive ? 'fail' : 'warn';
+  const why = dirs.has('private') ? '`private` is not accepted by Intuit — it still allows browser caching.' : cc ? 'Missing no-store.' : 'No Cache-Control header.';
+  return r(id, req, status, `Sensitive page cacheable: ${path}`, `Cache-Control: ${cc || '(none)'}${pragma ? `, Pragma: ${pragma}` : ''}. ${why}`,
+    { fix: 'Send `Cache-Control: no-store, no-cache, must-revalidate` and `Pragma: no-cache` on every authenticated or token-handling response.' });
+}
+
+export function analyzeCookies(responses) {
+  const seen = new Map();
+  for (const res of responses) for (const sc of res.setCookies || []) {
+    const c = parseSetCookie(sc);
+    if (!seen.has(c.name)) seen.set(c.name, { ...c, url: res.url });
+  }
+  if (seen.size === 0) return [r('cookies', 'cookie-flags', 'skip', 'No cookies observed', 'No Set-Cookie headers on probed URLs. Probe your login/callback with --path to see session cookies.')];
+  const out = [];
+  for (const c of seen.values()) {
+    const missing = ['secure', 'httponly'].filter((a) => !c.attrs.has(a));
+    const session = SESSION_COOKIE.test(c.name);
+    // CSRF double-submit cookies must be JS-readable; only require Secure on them.
+    const csrfToken = /csrf|xsrf/i.test(c.name);
+    const required = csrfToken ? missing.filter((m) => m === 'secure') : missing;
+    if (required.length === 0) {
+      const ss = c.sameSite ? `SameSite=${c.sameSite}` : 'no SameSite (consider Lax)';
+      out.push(r(`cookie:${c.name}`, 'cookie-flags', 'pass', `Cookie ${c.name} is Secure${csrfToken ? '' : ' + HttpOnly'}`, ss));
+    } else {
+      out.push(r(`cookie:${c.name}`, 'cookie-flags', session ? 'fail' : 'warn', `Cookie ${c.name} missing ${required.join(' + ')}`,
+        `${session ? 'Looks like a session/auth cookie. ' : ''}Set-Cookie: ${c.raw.slice(0, 160)}`,
+        { fix: 'Set `Secure; HttpOnly; SameSite=Lax` on session cookies (e.g. express-session `cookie: { secure: true, httpOnly: true }`).' }));
+    }
+  }
+  return out;
+}
+
+export function analyzeTrace(outcome, method = 'TRACE') {
+  const req = 'http-methods';
+  if (outcome.error) return r(`method:${method}`, req, 'pass', `${method} refused`, `Connection rejected: ${outcome.error}`);
+  const echoed = /^TRACE |x-qbrc-probe/i.test(outcome.body || '');
+  if (outcome.status >= 200 && outcome.status < 300) {
+    return r(`method:${method}`, req, 'fail', `${method} enabled`, `${method} ${outcome.url} → ${outcome.status}${echoed ? ' and echoed the request (Cross-Site Tracing)' : ''}.`,
+      { fix: `Disable ${method} at the web server / load balancer (nginx: \`if ($request_method !~ ^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)$) { return 405; }\`).` });
+  }
+  return r(`method:${method}`, req, 'pass', `${method} disabled`, `${method} → ${outcome.status}`);
+}
+
+export function analyzeAllow(outcome) {
+  if (outcome.error) return null;
+  const allow = String(outcome.headers.allow || outcome.headers['access-control-allow-methods'] || '');
+  if (!allow) return null;
+  const bad = allow.split(',').map((m) => m.trim().toUpperCase()).filter((m) => ['TRACE', 'TRACK', 'CONNECT'].includes(m));
+  if (bad.length) return r('method:allow', 'http-methods', 'warn', `Server advertises ${bad.join(', ')}`, `OPTIONS Allow: ${allow}`);
+  return r('method:allow', 'http-methods', 'info', 'Advertised methods', `OPTIONS Allow: ${allow}. Confirm each is actually used.`);
+}
+
+export function analyzeTokenEndpoint(res) {
+  const req = 'token-endpoint-302';
+  const path = new URL(res.url).pathname;
+  const html = isHtml(res);
+  const refPolicy = String(res.headers['referrer-policy'] || '').toLowerCase();
+  const safeReferrer = /no-referrer|same-origin|strict-origin/.test(refPolicy);
+  if (res.status >= 300 && res.status < 400) {
+    const loc = String(res.headers.location || '');
+    if (/[?&](code|access_token|refresh_token|realmId|id_token)=/i.test(loc)) {
+      return r(`token-endpoint:${path}`, req, 'fail', `${path} forwards tokens in the redirect`, `Location: ${loc}`, { fix: 'Exchange the code server-side and redirect to a clean URL without token/realmId parameters.' });
+    }
+    return r(`token-endpoint:${path}`, req, 'pass', `${path} responds with ${res.status} redirect`, `Location: ${loc || '(none)'}`);
+  }
+  if (html) {
+    return r(`token-endpoint:${path}`, req, 'fail', `${path} returns HTML with tokens in the URL`,
+      `GET ${path}?code=…&realmId=… → ${res.status} text/html. Any third-party resource on that page receives the code and realmId via Referer.${safeReferrer ? ` (Referrer-Policy: ${refPolicy} mitigates, but Intuit still requires a redirect.)` : ''}`,
+      { fix: 'Handle the callback server-side and always answer with `302 Found` — on success and on error (redirect to an error page without the parameters).' });
+  }
+  // An error for a request it cannot place (unknown state, missing code) has nowhere safe to
+  // redirect to. What the rule guards against is HTML in the response, which a non-HTML error avoids.
+  if (res.status >= 400) {
+    return r(`token-endpoint:${path}`, req, 'pass', `${path} answers invalid requests without HTML`, `GET ${path} with a fake code and state → ${res.status} ${res.headers['content-type'] || ''}. No page is rendered, so nothing can leak through Referer. A real authorization should still end in a 302; test that with a real connect flow.`);
+  }
+  return r(`token-endpoint:${path}`, req, 'warn', `${path} returns ${res.status} without redirect`, `Body is not HTML (${res.headers['content-type'] || 'no content-type'}), so Referer leakage is unlikely, but Intuit expects a 302.`);
+}
+
+export function analyzeOpenRedirect(res, param) {
+  const loc = String(res.headers.location || '');
+  if (res.status >= 300 && res.status < 400 && loc.startsWith(EVIL)) {
+    // The same parameter can be open on several paths; keep one result per path and parameter.
+    const path = new URL(res.url).pathname;
+    return r(`open-redirect:${path}?${param}`, 'open-redirect', 'fail', `Open redirect via ${path}?${param}=`, `${res.url} → ${loc}`, { fix: 'Only redirect to relative paths or an allow-list of hosts.' });
+  }
+  return null;
+}
+
+export function analyzeDisclosure(res) {
+  const out = [];
+  const server = res.headers.server;
+  const powered = res.headers['x-powered-by'];
+  const versioned = [server, powered].filter((h) => h && /\d+\.\d+/.test(h));
+  if (versioned.length) out.push(r('disclosure', 'patching-logging', 'warn', 'Server version disclosed', `${versioned.join(' / ')} — reviewers use this to flag unpatched software.`, { fix: 'Hide version banners (nginx `server_tokens off;`, Express `app.disable("x-powered-by")`).' }));
+  else if (powered) out.push(r('disclosure', 'patching-logging', 'info', 'X-Powered-By header present', `X-Powered-By: ${powered}`));
+  return out;
+}
+
+export function analyzeSecurityHeaders(res) {
+  const missing = [];
+  const csp = String(res.headers['content-security-policy'] || '');
+  if (!/frame-ancestors/.test(csp) && !res.headers['x-frame-options']) missing.push('X-Frame-Options or CSP frame-ancestors (clickjacking)');
+  if (!res.headers['x-content-type-options']) missing.push('X-Content-Type-Options: nosniff');
+  if (!csp) missing.push('Content-Security-Policy (XSS defense in depth)');
+  if (!missing.length) return r('security-headers', 'xss', 'pass', 'Browser security headers present', 'CSP, framing and nosniff headers set.');
+  return r('security-headers', 'xss', 'warn', 'Missing browser security headers', missing.join('; '), { fix: 'Use helmet (Node), secure_headers (Rails) or equivalent.' });
+}
+
+// ---------- probes ----------
+
+async function safe(fn) {
+  try {
+    return await fn();
+  } catch (e) {
+    return { error: e.code || e.message };
+  }
+}
+
+/**
+ * @param {{ url: string, paths?: string[], callback?: string, headers?: Record<string, string>, timeout?: number,
+ *   log?: (m: string) => void, onResult?: (r: object) => void, lookup?: Function, httpPort?: number }} opts
+ */
+// onResult streams each result as soon as it is known; lookup lets a hosted scanner pin DNS to vetted IPs.
+export async function runRuntime({ url, paths = [], callback, headers = {}, timeout = 10000, log = () => {}, onResult, lookup, httpPort }) {
+  const base = new URL(url);
+  if (base.protocol !== 'https:') base.protocol = 'https:';
+  const results = [];
+  const push = (...items) => {
+    for (const item of items) {
+      results.push(item);
+      onResult?.(item);
+    }
+  };
+  const responses = [];
+  const at = (p) => new URL(p, base).toString();
+
+  log(`GET ${base.href}`);
+  const home = await safe(() => request(base.href, { headers, timeout, lookup }));
+  if (home.error) {
+    push(r('reachable', 'https-everywhere', 'fail', 'HTTPS endpoint unreachable', `${base.href}: ${home.error}`));
+    return results;
+  }
+  responses.push(home);
+
+  // HTTPS everywhere
+  const httpUrl = new URL(base.href);
+  httpUrl.protocol = 'http:';
+  // Plain HTTP on port 80 unless told otherwise (local test servers run on high ports).
+  httpUrl.port = httpPort ? String(httpPort) : '';
+  log(`GET ${httpUrl.href}`);
+  const plain = await safe(() => request(httpUrl.href, { timeout, lookup }));
+  push(analyzeHttpToHttps({ url: httpUrl.href, ...plain }));
+
+  // TLS
+  const port = Number(base.port || 443);
+  log(`TLS handshakes ${base.hostname}:${port}`);
+  const [v10, v11, v12, v13] = await Promise.all(['TLSv1', 'TLSv1.1', 'TLSv1.2', 'TLSv1.3'].map((v) => tlsHandshake(base.hostname, port, v, { lookup })));
+  push(...analyzeTls({ v10, v11, v12, v13 }));
+
+  // Cache-Control on sensitive pages (user-specified; else the callback and home page)
+  const sensitive = paths.length ? paths : [base.pathname];
+  for (const p of sensitive) {
+    const target = at(p);
+    log(`GET ${target}`);
+    const res = p === base.pathname ? home : await safe(() => request(target, { headers, timeout, lookup }));
+    if (res.error) {
+      push(r(`cache-control:${p}`, 'cache-control', 'warn', `Could not fetch ${p}`, res.error));
+      continue;
+    }
+    if (res !== home) responses.push(res);
+    push(analyzeCacheControl(res, { sensitive: paths.length > 0 }));
+  }
+
+  // HTTP methods
+  for (const m of ['TRACE', 'TRACK']) {
+    log(`${m} ${base.href}`);
+    const res = await safe(() => request(base.href, { method: m, headers: { 'x-qbrc-probe': '1' }, timeout, lookup }));
+    push(analyzeTrace(res.error ? { ...res, url: base.href } : res, m));
+  }
+  const opt = await safe(() => request(base.href, { method: 'OPTIONS', timeout, lookup }));
+  const allow = analyzeAllow(opt);
+  if (allow) push(allow);
+
+  // Token endpoint / OAuth callback
+  if (callback) {
+    const cb = new URL(at(callback));
+    cb.searchParams.set('code', 'QBRC_FAKE_AUTH_CODE');
+    cb.searchParams.set('state', 'qbrc-probe-state');
+    cb.searchParams.set('realmId', '9130000000000000');
+    log(`GET ${cb.href}`);
+    const res = await safe(() => request(cb.href, { headers: { ...headers, referer: 'https://appcenter.intuit.com/' }, timeout, lookup }));
+    if (res.error) push(r('token-endpoint', 'token-endpoint-302', 'warn', 'Callback unreachable', `${cb.href}: ${res.error}`));
+    else if (res.status === 404) push(r('token-endpoint', 'token-endpoint-302', 'warn', `Callback ${callback} returned 404`, 'Check the --callback path matches the Redirect URI registered in the Intuit developer portal.'));
+    else {
+      responses.push(res);
+      push(analyzeTokenEndpoint(res));
+      push(analyzeCacheControl(res, { sensitive: true }));
+    }
+  } else {
+    push(r('token-endpoint', 'token-endpoint-302', 'skip', 'OAuth callback not probed', 'Pass --callback /your/oauth/callback to verify the 302 rule.'));
+  }
+
+  // Open redirects on home and callback
+  const redirectTargets = [base.pathname, callback].filter(Boolean);
+  const probes = redirectTargets.flatMap((p) => REDIRECT_PARAMS.map((param) => ({ p, param })));
+  const found = await Promise.all(probes.map(async ({ p, param }) => {
+    const u = new URL(at(p));
+    u.searchParams.set(param, EVIL);
+    const res = await safe(() => request(u.href, { headers, timeout, lookup }));
+    return res.error ? null : analyzeOpenRedirect(res, param);
+  }));
+  const hits = found.filter(Boolean);
+  push(...hits);
+  const openRedirect = hits.length > 0;
+  if (!openRedirect) push(r('open-redirect', 'open-redirect', 'pass', 'No open redirect found', `Probed ${REDIRECT_PARAMS.length} common redirect parameters on ${redirectTargets.join(', ')}.`));
+
+  push(analyzeHsts(responses.filter((res) => res.url.startsWith('https:'))));
+  push(...analyzeCookies(responses));
+  push(...analyzeDisclosure(home));
+  push(analyzeSecurityHeaders(home));
+  return results;
+}

package/src/scan-core.js

@@ -0,0 +1,211 @@
+export const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.nuxt', '.output', '.vercel', 'vendor', 'coverage', 'out', 'target', '__pycache__', '.venv', 'venv', 'bin', 'obj', '.turbo', '.cache']);
+export const EXTS = new Set(['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.mts', '.cts', '.vue', '.svelte', '.py', '.rb', '.php', '.java', '.kt', '.cs', '.go', '.ejs', '.erb', '.hbs', '.html']);
+const TEST_FILE = /(^|[\\/])(test|tests|__tests__|__mocks__|spec|fixtures?|examples?)[\\/]|\.(test|spec)\.[a-z]+$/i;
+export const MAX_BYTES = 1024 * 1024;
+
+const TOKEN_WORDS = String.raw`(access_?token|refresh_?token|accessToken|refreshToken|realm_?id|realmId|client_?secret|clientSecret|authResponse|getToken\(\)|getJson\(\)|bearer)`;
+
+// Line rules. `status` is the result status when the rule matches.
+export const LINE_RULES = [
+  {
+    id: 'log-token', requirement: 'patching-logging', status: 'fail',
+    title: 'OAuth tokens or realmId written to logs',
+    re: new RegExp(String.raw`(console\.(log|info|debug|warn|error|trace)|\blogger\.\w+|\blog\.(info|debug|warn|error|trace)|\bprint(ln|f)?\s*\(|\bputs\b|\blogging\.\w+|Log\.(d|i|e|w)\(|\berror_log\(|fmt\.Print)[^\n]*\b${TOKEN_WORDS}`, 'i'),
+    fix: 'Never log tokens, realmId, or QuickBooks payloads. Log a token fingerprint (last 4 chars) or a request id instead.',
+  },
+  {
+    id: 'inline-key', requirement: 'key-storage', status: 'fail',
+    title: 'Encryption key hardcoded in source',
+    re: /\b(encrypt(ion)?_?key|aes_?key|cipher_?key|crypto_?key|token_?key|secret_?key)\b\s*[:=]\s*['"`][^'"`\s]{12,}['"`]|createCipheriv\(\s*['"`][^'"`]+['"`]\s*,\s*['"`]/i,
+    fix: 'Load the AES key from a separate config file or secret manager (env var, AWS KMS, Vault) — Intuit requires it not be inline.',
+  },
+  {
+    id: 'inline-client-secret', requirement: 'token-exposure', status: 'fail',
+    title: 'Intuit client secret hardcoded in source',
+    re: /\bclient_?secret\b['"]?\s*[:=]\s*['"`][A-Za-z0-9]{30,}['"`]/i,
+    fix: 'Move the client secret to environment/secret storage and rotate it in the Intuit developer portal.',
+  },
+  {
+    id: 'tls-verify-off', requirement: 'https-everywhere', status: 'fail',
+    title: 'TLS certificate verification disabled',
+    re: /rejectUnauthorized\s*:\s*false|NODE_TLS_REJECT_UNAUTHORIZED\s*=\s*['"]?0|verify\s*=\s*False|InsecureSkipVerify\s*:\s*true|CURLOPT_SSL_VERIFYPEER\s*,\s*(false|0)|ServerCertificateValidationCallback\s*=.*=>\s*true/,
+    fix: 'Never disable certificate validation; tokens can be intercepted by a MITM.',
+  },
+  {
+    id: 'token-to-browser', requirement: 'token-exposure', status: 'fail',
+    title: 'OAuth tokens sent to or stored in the browser',
+    re: new RegExp(String.raw`(localStorage|sessionStorage)\.setItem\([^)]*(token|realm)|res\.(json|send|end|write)\([^)]*\b(refresh_?token|refreshToken|authResponse|getJson\(\)|oauthClient\.getToken\(\)|getToken\(\))|jsonify\([^)]*refresh_token|[?&](access_token|refresh_token)=\$\{|[?&](access_token|refresh_token)=['"]?\s*\+`, 'i'),
+    fix: 'Keep Intuit tokens server-side only. The browser should hold an opaque session cookie, never access/refresh tokens or realmId.',
+  },
+  {
+    id: 'weak-cipher', requirement: 'token-encryption', status: 'warn',
+    title: 'Weak or deprecated encryption mode',
+    re: /createCipher\(|createDecipher\(|aes-\d+-ecb|AES\.MODE_ECB|AES\/ECB|\brc4\b|des-cbc['"]|DES\/CBC|Cipher\.getInstance\(\s*"AES"\s*\)/i,
+    fix: 'Use AES-256-GCM (or AES-256-CBC + HMAC) with a random IV per record via createCipheriv / AESGCM.',
+  },
+  {
+    id: 'cookie-flag-off', requirement: 'cookie-flags', status: 'warn',
+    title: 'Cookie configured without Secure/HttpOnly',
+    re: /\b(httpOnly|http_only|httponly)\s*[:=]\s*(false|False)|\bsecure\s*:\s*false\b|SESSION_COOKIE_SECURE\s*=\s*False|SESSION_COOKIE_HTTPONLY\s*=\s*False/,
+    fix: 'Set secure: true and httpOnly: true for session cookies in every non-local environment.',
+  },
+  {
+    id: 'sql-concat', requirement: 'injection', status: 'warn',
+    title: 'SQL built with string interpolation',
+    re: /(\.query|\.execute|\.exec|\.raw|\$queryRawUnsafe|\$executeRawUnsafe|knex\.raw|sequelize\.query|db\.run|cursor\.execute)\s*\(\s*(`[^`]*\$\{|['"][^'"]*\b(SELECT|INSERT|UPDATE|DELETE)\b[^'"]*['"]\s*\+|f['"][^'"]*\b(SELECT|INSERT|UPDATE|DELETE)\b|['"][^'"]*%s[^'"]*['"]\s*%)/i,
+    fix: 'Use parameterized queries / prepared statements.',
+  },
+  {
+    id: 'qbo-query-concat', requirement: 'injection', status: 'warn',
+    title: 'QuickBooks query built with string interpolation',
+    re: /\bselect\s+\*?\s*[\w,\s]*\s+from\s+(Invoice|Customer|Vendor|Bill|Item|Account|Payment|Estimate)\b[^'"`]*(\$\{|['"`]\s*\+)/i,
+    fix: 'Escape single quotes in values interpolated into QuickBooks query language (e.g. DisplayName = \'O\\\'Brien\').',
+  },
+  {
+    id: 'xss-sink', requirement: 'xss', status: 'warn',
+    title: 'Unescaped HTML output sink',
+    re: /dangerouslySetInnerHTML|\.innerHTML\s*=(?!=)|\bv-html=|\{\{\{|<%-|\|\s*safe\b|\.html_safe\b|\bmark_safe\(|@Html\.Raw\(|\{@html\s/,
+    fix: 'Make sure QuickBooks data (customer names, memos) and user input are escaped or sanitized (DOMPurify) before rendering.',
+  },
+  {
+    id: 'xxe', requirement: 'injection', status: 'warn',
+    title: 'XML parser may resolve external entities',
+    re: /noent\s*:\s*true|resolve_entities\s*=\s*True|XmlUrlResolver\(|DtdProcessing\.Parse|LIBXML_NOENT|setExpandEntityReferences\(\s*true/,
+    fix: 'Disable DTDs/external entity resolution in XML parsers.',
+  },
+];
+
+const INTUIT_REF = /intuit-oauth|node-quickbooks|quickbooks|oauth\.platform\.intuit\.com|appcenter\.intuit\.com|intuitlib|IntuitAuthorization|realmId|realm_id|com\.intuit\.oauth2/i;
+const AUTHORIZE_REF = /authorizeUri|authorize_url|get_authorization_url|appcenter\.intuit\.com\/connect\/oauth2|OAuth2PlatformClient|getAuthorizationURL/i;
+const STATIC_STATE = /\bstate(_token)?\s*[:=]\s*['"`]([A-Za-z0-9_-]{2,40})['"`]/;
+const STATE_CHECK = /\bstate\b[^\n]{0,80}(!==|===|!=|==|\bnot in\b|\bequals\()|(req\.query|request\.args|params|searchParams|query)\W{0,3}\.?(get\(\s*['"])?state\b[^\n]{0,120}(session|cookie|stored|expected)|validateState|verifyState|check_state|state_matches|timingSafeEqual/i;
+const CSRF_LIB = /\bcsurf\b|csrf-csrf|\blusca\b|@fastify\/csrf|@edge-csrf|CsrfViewMiddleware|protect_from_forgery|csrf_token|ValidateAntiForgeryToken|next-csrf|csrf\(\)|tiny-csrf|SameSite=Strict|sameSite\s*:\s*['"](strict|lax)/i;
+const PERSIST_TOKEN = /\b(refresh_?token|refreshToken)\b[^\n]{0,160}\b(save|insert|update|upsert|create|set|put|write|store|persist|hset|setex|INSERT|UPDATE)\b|\b(save|insert|update|upsert|create|store|persist|hset|setex)\w*\s*\([^\n]{0,160}\b(refresh_?token|refreshToken)\b|\b(refresh_?token|refreshToken)\s*[:=]\s*(token|authResponse|response|tokens|json|data|oauth)/i;
+const PERSIST_REALM = /\b(realm_?id|realmId)\b[^\n]{0,120}\b(save|insert|update|upsert|create|store|persist|INSERT|UPDATE)\b|\b(save|insert|update|upsert|create|store|persist)\w*\s*\([^\n]{0,160}\b(realm_?id|realmId)\b|\b(realm_?id|realmId)\s*:\s*(req|request|params|query|url|searchParams|token|authResponse)\b/i;
+const ENCRYPT_EVIDENCE = /createCipheriv\(\s*['"`]?(aes|des-ede3)|createCipheriv\(|crypto\.subtle\.encrypt|['"]AES-GCM['"]|AES\.new\(|AESGCM\(|\bFernet\(|Cipher\.getInstance\(\s*"(AES|DESede)|openssl_encrypt\(|ActiveRecord::Encryption|\bencrypts\s+:|attr_encrypted|lockbox|TripleDES|des-ede3|@47ng\/cloak|prisma-field-encryption|mongoose-(field-)?encryption|crypto-js[^\n]*AES|CryptoJS\.AES|kms[\w.]*\.?encrypt|EncryptCommand|secretbox|AesGcm|Aes\.Create\(|\bencrypt(Token|RefreshToken|Secret|Field|Value)?\s*\(/i;
+const THIRD_PARTY = [
+  { re: /['"](openai|@anthropic-ai\/sdk|@google\/generative-ai|@ai-sdk\/[\w-]+|ai|langchain|@langchain\/[\w-]+|cohere-ai)['"]|^\s*(import|from)\s+(openai|anthropic|langchain)\b/m, name: 'LLM provider' },
+  { re: /['"](@segment\/analytics-node|analytics-node|mixpanel|posthog-node|posthog-js|amplitude|@amplitude\/[\w-]+|@hubspot\/api-client|intercom-client|heap-api)['"]/, name: 'analytics / CRM SDK' },
+  { re: /['"](@sentry\/[\w-]+|@datadog\/[\w-]+|dd-trace|newrelic|@logtail\/[\w-]+|logrocket|@bugsnag\/[\w-]+|rollbar)['"]|^\s*import\s+sentry_sdk/m, name: 'error/APM SDK' },
+];
+const APIDECK_REF = /@apideck\/[\w-]+|unify\.apideck\.com|vault\.apideck\.com|x-apideck-consumer-id|apideck-unify|from apideck_unify|apideck\.vault/i;
+const QBO_DATA = /\b(Invoice|Customer|Vendor|Bill|JournalEntry|Payment|SalesReceipt|CompanyInfo|getInvoice|findCustomers|findInvoices|QueryResponse)\b/;
+
+// Decide whether a file (by basename) is scanned as code, as a local env file, or skipped.
+export function classifyFile(name) {
+  if (/^\.env(\.|$)/.test(name)) return /example|sample|template|dist/.test(name) ? null : 'env';
+  if (/\.min\.js$/.test(name)) return null;
+  const dot = name.lastIndexOf('.');
+  return dot > 0 && EXTS.has(name.slice(dot).toLowerCase()) ? 'code' : null;
+}
+
+export function isSkippedDir(name) {
+  return SKIP_DIRS.has(name) || name.startsWith('.');
+}
+
+const loc = (file, line, text) => ({ file, line, snippet: text.trim().slice(0, 160) });
+
+// files: [{ rel, text, kind: 'code' | 'env' }] — pure, so it runs in Node and in the browser.
+export function scanFiles(files, { includeTests = false } = {}) {
+  const hits = new Map(LINE_RULES.map((rule) => [rule.id, []]));
+  const evidence = { apideck: [], intuit: [], authorize: [], staticState: [], stateCheck: [], csrfLib: [], persistToken: [], persistRealm: [], encrypt: [], thirdParty: new Map(), envSecrets: [] };
+  let scanned = 0;
+
+  for (const f of files) {
+    if (f.text.length > MAX_BYTES) continue;
+    const { text } = f;
+    scanned++;
+
+    if (f.kind === 'env') {
+      text.split('\n').forEach((l, i) => {
+        if (/^\s*(\w*(CLIENT_SECRET|ENCRYPTION_KEY|AES_KEY|REFRESH_TOKEN)\w*)\s*=\s*\S{8,}/i.test(l)) evidence.envSecrets.push(loc(f.rel, i + 1, l.replace(/=.*/, '=***')));
+      });
+      continue;
+    }
+    const isTest = TEST_FILE.test(f.rel);
+    if (isTest && !includeTests) continue;
+
+    const lines = text.split('\n');
+    const fileIntuit = INTUIT_REF.test(text);
+    const fileAuthorize = AUTHORIZE_REF.test(text);
+    const fileQbo = fileIntuit && QBO_DATA.test(text);
+
+    lines.forEach((line, i) => {
+      if (line.length > 2000) return;
+      const n = i + 1;
+      for (const rule of LINE_RULES) if (rule.re.test(line)) hits.get(rule.id).push(loc(f.rel, n, line));
+      if (APIDECK_REF.test(line)) evidence.apideck.push(loc(f.rel, n, line));
+      if (fileIntuit && INTUIT_REF.test(line)) evidence.intuit.push(loc(f.rel, n, line));
+      if (AUTHORIZE_REF.test(line)) evidence.authorize.push(loc(f.rel, n, line));
+      if (fileAuthorize) {
+        const m = STATIC_STATE.exec(line);
+        if (m && !/^(state|query|params|body)$/i.test(m[2])) evidence.staticState.push(loc(f.rel, n, line));
+      }
+      if (STATE_CHECK.test(line)) evidence.stateCheck.push(loc(f.rel, n, line));
+      if (CSRF_LIB.test(line)) evidence.csrfLib.push(loc(f.rel, n, line));
+      if (PERSIST_TOKEN.test(line)) evidence.persistToken.push(loc(f.rel, n, line));
+      if (PERSIST_REALM.test(line)) evidence.persistRealm.push(loc(f.rel, n, line));
+      if (ENCRYPT_EVIDENCE.test(line)) evidence.encrypt.push(loc(f.rel, n, line));
+    });
+
+    if (fileQbo) for (const tp of THIRD_PARTY) if (tp.re.test(text)) {
+      if (!evidence.thirdParty.has(tp.name)) evidence.thirdParty.set(tp.name, []);
+      evidence.thirdParty.get(tp.name).push(loc(f.rel, 1, `imports ${tp.name}`));
+    }
+  }
+
+  return { scanned, results: buildResults(hits, evidence) };
+}
+
+const res = (id, requirement, status, title, detail, extra = {}) => ({ id, requirement, status, title, detail, ...extra });
+
+function buildResults(hits, ev) {
+  const out = [];
+  if (!ev.intuit.length) {
+    out.push(res('src:intuit', 'token-encryption', 'warn', 'No QuickBooks integration code detected', 'Could not find intuit-oauth, node-quickbooks, realmId or Intuit OAuth URLs. OAuth-specific checks below are less reliable. (If you connect to QuickBooks through Apideck Vault, Intuit tokens are stored and encrypted by Apideck, not your app.)'));
+  }
+
+  for (const rule of LINE_RULES) {
+    const h = hits.get(rule.id);
+    if (h.length) out.push(res(`src:${rule.id}`, rule.requirement, rule.status, rule.title, `${h.length} occurrence${h.length > 1 ? 's' : ''}.`, { locations: h.slice(0, 15), fix: rule.fix }));
+  }
+
+  // OAuth CSRF (state parameter)
+  if (ev.staticState.length) {
+    out.push(res('src:static-state', 'csrf', 'fail', 'OAuth state parameter is a constant', 'The authorize URL uses a hardcoded `state` (Intuit\'s sample code ships `testState`). That disables CSRF protection on the connect flow.',
+      { locations: ev.staticState.slice(0, 10), fix: 'Generate a random state per request (crypto.randomBytes(32)), store it in the session, and compare it in the callback before exchanging the code.' }));
+  } else if (ev.authorize.length && !ev.stateCheck.length) {
+    out.push(res('src:state-check', 'csrf', 'warn', 'No OAuth state validation found', 'Found an Intuit authorize URL but no code comparing the returned `state` to a stored value.', { locations: ev.authorize.slice(0, 5), fix: 'Verify `state` in the callback with a constant-time compare before calling createToken.' }));
+  } else if (ev.authorize.length) {
+    out.push(res('src:state-check', 'csrf', 'pass', 'OAuth state appears to be validated', 'Found state comparison logic.', { locations: ev.stateCheck.slice(0, 3) }));
+  }
+  if (ev.csrfLib.length) out.push(res('src:csrf-lib', 'csrf', 'pass', 'CSRF protection in place', 'Found CSRF middleware or SameSite cookie configuration.', { locations: ev.csrfLib.slice(0, 3) }));
+  else out.push(res('src:csrf-lib', 'csrf', 'warn', 'No CSRF middleware detected', 'No CSRF library or SameSite cookie config found. Intuit\'s pen test checks state-changing forms and endpoints.', { fix: 'Add CSRF tokens (csrf-csrf, Django/Rails built-ins) or SameSite=Lax/Strict session cookies plus origin checks.' }));
+
+  // Token encryption at rest
+  const persisted = ev.persistToken.length > 0;
+  if (persisted && !ev.encrypt.length) {
+    out.push(res('src:token-encryption', 'token-encryption', 'fail', 'Refresh token stored without encryption', 'Found code persisting the refresh token but no AES/3DES encryption anywhere in the codebase.',
+      { locations: ev.persistToken.slice(0, 10), fix: 'Encrypt refresh token and realmId with AES-256-GCM before writing them (see README for a 20-line helper).' }));
+  } else if (persisted) {
+    out.push(res('src:token-encryption', 'token-encryption', 'pass', 'Encryption used near token storage', 'Found both token persistence and AES/3DES encryption. Confirm the refresh token *and* realmId pass through it before every write.',
+      { locations: [...ev.persistToken.slice(0, 3), ...ev.encrypt.slice(0, 3)] }));
+  } else if (ev.apideck.length && !ev.authorize.length) {
+    out.push(res('src:token-encryption', 'token-encryption', 'pass', 'Intuit tokens held by Apideck Vault', 'This app connects to QuickBooks through Apideck and runs no Intuit OAuth flow of its own, so refresh tokens and realmId are stored and encrypted by Apideck. Make sure your Apideck API key stays server-side.', { locations: ev.apideck.slice(0, 2) }));
+  } else if (ev.intuit.length) {
+    out.push(res('src:token-encryption', 'token-encryption', 'warn', 'Could not locate refresh-token storage', 'Intuit code found, but no obvious write of the refresh token. If you persist it (you must, to stay connected), make sure it is AES-encrypted.'));
+  }
+  if (ev.persistRealm.length && !ev.encrypt.length) {
+    out.push(res('src:realm-encryption', 'token-encryption', 'fail', 'realmId stored without encryption', 'Intuit requires realmId to be encrypted at rest along with the refresh token.', { locations: ev.persistRealm.slice(0, 5) }));
+  }
+
+  // Key storage
+  if (!hits.get('inline-key').length && ev.encrypt.length) out.push(res('src:key-storage', 'key-storage', 'pass', 'No inline encryption key found', 'Encryption keys appear to be loaded from configuration.'));
+  if (ev.envSecrets.length) out.push(res('src:env-secrets', 'key-storage', 'warn', 'Secrets present in local .env files', 'Make sure these files are git-ignored and never deployed to the client bundle.', { locations: ev.envSecrets.slice(0, 10) }));
+
+  // Third-party data sharing
+  for (const [name, locs] of ev.thirdParty) {
+    out.push(res(`src:third-party:${name}`, 'no-third-party-access', 'warn', `QuickBooks data code also imports ${name}`, `Files that handle QuickBooks entities import a ${name}. Intuit prohibits sending customer QuickBooks data to third parties outside your app's function — verify payloads${name.startsWith('error') ? ' are scrubbed (e.g. Sentry beforeSend)' : ''}.`, { locations: locs.slice(0, 10) }));
+  }
+  return out;
+}

package/src/source.js

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { classifyFile, isSkippedDir, scanFiles, MAX_BYTES } from './scan-core.js';
+
+export { LINE_RULES, scanFiles } from './scan-core.js';
+
+function walk(dir, root, files) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (!isSkippedDir(e.name)) walk(full, root, files);
+    } else if (e.isFile()) {
+      const kind = classifyFile(e.name);
+      if (kind) files.push({ full, rel: path.relative(root, full), kind });
+    }
+  }
+}
+
+export function scanSource(root, opts = {}) {
+  const abs = path.resolve(root);
+  const found = [];
+  walk(abs, abs, found);
+  const files = [];
+  for (const f of found) {
+    try {
+      if (fs.statSync(f.full).size > MAX_BYTES) continue;
+      files.push({ rel: f.rel, kind: f.kind, text: fs.readFileSync(f.full, 'utf8') });
+    } catch {
+      // unreadable file; skip
+    }
+  }
+  return { root: abs, ...scanFiles(files, opts) };
+}