brainblast 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DSB-117
+
+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

@@ -0,0 +1,66 @@
+# brainblast
+
+Deterministic auditor for catastrophic AI-integration bugs. Point it at a repo;
+it finds the silent money/auth traps an AI agent ships, and generates the
+behavioral test that proves they're fixed. No LLM, no API key, no network — it
+parses your code statically and runs offline.
+
+## Use
+
+```sh
+npx brainblast .            # scan the repo, write .agent-research/report.json
+npx brainblast . --ci       # exit 1 if a confirmed CRITICAL remains
+npx brainblast . --ci --strict   # also fail on CANT_TELL (can't statically prove)
+```
+
+Exit codes: **0** clean · **1** a confirmed FAIL at/above the threshold · CANT_TELL
+is a warning by default (a red build always means a real, confirmed problem).
+
+## What it catches (today, Node/TypeScript)
+
+- **Stripe webhooks** that don't verify the signature on the **raw** body →
+  forged `payment_intent.succeeded` events accepted.
+- **Privy / JWT** access tokens decoded without verifying the signature, or
+  without asserting `aud` + `iss` → auth bypass / cross-app token reuse.
+- **Bags (Solana token launch)** fee-share configs that omit the creator from
+  `feeClaimers`, or whose `userBps` don't sum to 10000 → the creator earns **zero
+  fees forever** (the config is immutable on-chain after launch).
+
+Each finding lands in `report.json` (stable, versioned `schemaVersion: "1.0"`)
+with a `checks[]` array a CI gate can read.
+
+## Rules are data
+
+Detection lives in `*.yaml` rules (facts) that bind to a small set of vetted,
+human-maintained checker + test templates by `kind` — never executable code in a
+rule. Drop project-specific rules in `.agent-research/rules/*.yaml` and the
+auditor loads them on top of the bundled pack (they can add traps, not shadow
+bundled ones). Invalid rules are rejected at load.
+
+## Library API
+
+```ts
+import { audit, resolveRules } from "brainblast";
+const { checks, report } = audit(process.cwd(), resolveRules(process.cwd()));
+```
+
+## Security model
+
+- **The audit is static.** `brainblast <dir>` parses source with ts-morph and
+  never executes it, so auditing untrusted code does not run it. YAML rules are
+  data only (no code execution, no prototype pollution).
+- **Generated behavioral tests execute the audited repo's code when you run
+  them.** That's expected when you audit your own repo. If you run brainblast on
+  untrusted code (e.g. a fork PR) and then run the generated tests, run them in a
+  sandbox — the same caution as running any untrusted test suite.
+
+## Develop
+
+```sh
+npm install
+npm test         # unit suite
+npm run prove    # end-to-end: generated tests RED on vulnerable, GREEN on fixed
+npm run build    # produce dist/ (the published artifact)
+```
+
+MIT.

package/dist/chunk-H2Y75CSH.js

@@ -0,0 +1,494 @@
+// src/finder.ts
+import { Project, SyntaxKind } from "ts-morph";
+
+// src/walk.ts
+import { readdirSync, statSync } from "fs";
+import { join } from "path";
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir)) {
+    if (entry === "node_modules" || entry === ".git" || entry === ".gen") continue;
+    const p = join(dir, entry);
+    const st = statSync(p);
+    if (st.isDirectory()) walk(p, out);
+    else if (p.endsWith(".ts") && !p.endsWith(".test.ts") && !p.endsWith(".d.ts")) out.push(p);
+  }
+  return out;
+}
+
+// src/finder.ts
+function bodyCallsAnyOf(fn, names) {
+  if (names.size === 0) return false;
+  return fn.getDescendantsOfKind(SyntaxKind.CallExpression).some((c) => {
+    const exp = c.getExpression();
+    if (exp.getKind() === SyntaxKind.Identifier) return names.has(exp.getText());
+    if (exp.getKind() === SyntaxKind.PropertyAccessExpression) {
+      return names.has(exp.asKind(SyntaxKind.PropertyAccessExpression).getName());
+    }
+    return false;
+  });
+}
+function findCandidates(targetDir, rule) {
+  const files = walk(targetDir);
+  const project = new Project({ skipAddingFilesFromTsConfig: true, compilerOptions: { allowJs: false } });
+  const modules = new Set(rule.detect.modules);
+  const triggers = new Set(rule.detect.triggerCalls);
+  const nameRe = new RegExp(rule.detect.nameRegex, "i");
+  const out = [];
+  for (const file of files) {
+    const sf = project.addSourceFileAtPath(file);
+    const importsModule = sf.getImportDeclarations().some((d) => modules.has(d.getModuleSpecifierValue()));
+    const consider = (fn, name) => {
+      if (!(importsModule || name && nameRe.test(name) || bodyCallsAnyOf(fn, triggers))) return;
+      out.push({
+        filePath: file,
+        fnName: name || "(anonymous)",
+        params: fn.getParameters().map((p) => p.getName()),
+        fn
+      });
+    };
+    for (const fn of sf.getFunctions()) consider(fn, fn.getName() ?? "");
+    for (const v of sf.getVariableDeclarations()) {
+      const arrow = v.getInitializerIfKind(SyntaxKind.ArrowFunction);
+      if (arrow) consider(arrow, v.getName());
+    }
+  }
+  return out;
+}
+
+// src/checkers/positionalArgIdentity.ts
+import { SyntaxKind as SyntaxKind2 } from "ts-morph";
+var positionalArgIdentity = (c, p) => {
+  const calls = c.fn.getDescendantsOfKind(SyntaxKind2.CallExpression).filter((call) => {
+    const exp = call.getExpression();
+    return exp.getKind() === SyntaxKind2.PropertyAccessExpression && exp.asKind(SyntaxKind2.PropertyAccessExpression).getName() === p.call;
+  });
+  if (calls.length === 0) return { result: "fail", detail: p.absentDetail };
+  const arg = calls[0].getArguments()[p.argIndex];
+  const wantParam = c.params[p.paramIndex];
+  if (arg && wantParam && arg.getKind() === SyntaxKind2.Identifier && arg.getText() === wantParam) {
+    return { result: "pass", detail: String(p.passDetail).replace("{param}", wantParam) };
+  }
+  if (arg && arg.getKind() === SyntaxKind2.CallExpression) {
+    return { result: "fail", detail: p.parsedDetail };
+  }
+  return {
+    result: "cant_tell",
+    detail: `Could not confirm argument ${p.argIndex} of ${p.call} is the raw input.`
+  };
+};
+
+// src/checkers/requiredCallWithOptions.ts
+import { SyntaxKind as SyntaxKind3 } from "ts-morph";
+function callName(call) {
+  const exp = call.getExpression();
+  if (exp.getKind() === SyntaxKind3.Identifier) return exp.getText();
+  if (exp.getKind() === SyntaxKind3.PropertyAccessExpression) {
+    return exp.asKind(SyntaxKind3.PropertyAccessExpression).getName();
+  }
+  return "";
+}
+function hasAllProps(call, groups) {
+  for (const arg of call.getArguments()) {
+    const obj = arg.asKind(SyntaxKind3.ObjectLiteralExpression);
+    if (!obj) continue;
+    const names = obj.getProperties().map((pr) => {
+      const pa = pr.asKind(SyntaxKind3.PropertyAssignment) ?? pr.asKind(SyntaxKind3.ShorthandPropertyAssignment);
+      return pa?.getName() ?? "";
+    });
+    if (groups.every((g) => g.some((n) => names.includes(n)))) return true;
+  }
+  return false;
+}
+var requiredCallWithOptions = (c, p) => {
+  const calls = c.fn.getDescendantsOfKind(SyntaxKind3.CallExpression);
+  const verify = calls.filter((x) => p.verifyCalls.includes(callName(x)));
+  const decode = calls.filter((x) => p.decodeCalls.includes(callName(x)));
+  if (verify.length > 0) {
+    if (verify.some((v) => hasAllProps(v, p.requiredProps))) {
+      return { result: "pass", detail: p.passDetail };
+    }
+    return { result: "fail", detail: p.missingPropsDetail };
+  }
+  if (decode.length > 0) return { result: "fail", detail: p.decodeOnlyDetail };
+  return { result: "cant_tell", detail: "No verification or decode call found." };
+};
+
+// src/checkers/feeAllocationShape.ts
+import { SyntaxKind as SyntaxKind4 } from "ts-morph";
+function callName2(call) {
+  const exp = call.getExpression();
+  if (exp.getKind() === SyntaxKind4.Identifier) return exp.getText();
+  if (exp.getKind() === SyntaxKind4.PropertyAccessExpression) {
+    return exp.asKind(SyntaxKind4.PropertyAccessExpression).getName();
+  }
+  return "";
+}
+function asArrayLiteral(expr, c) {
+  if (!expr) return void 0;
+  const direct = expr.asKind(SyntaxKind4.ArrayLiteralExpression);
+  if (direct) return direct;
+  if (expr.getKind() === SyntaxKind4.Identifier) {
+    const name = expr.getText();
+    for (const decl of c.fn.getDescendantsOfKind(SyntaxKind4.VariableDeclaration)) {
+      if (decl.getName() === name) {
+        return decl.getInitializerIfKind(SyntaxKind4.ArrayLiteralExpression);
+      }
+    }
+  }
+  return void 0;
+}
+function feeArray(call, prop, c) {
+  for (const arg of call.getArguments()) {
+    const obj = arg.asKind(SyntaxKind4.ObjectLiteralExpression);
+    if (!obj) continue;
+    const member = obj.getProperty(prop);
+    if (!member) continue;
+    const pa = member.asKind(SyntaxKind4.PropertyAssignment);
+    if (pa) return asArrayLiteral(pa.getInitializer(), c) ?? null;
+    const shorthand = member.asKind(SyntaxKind4.ShorthandPropertyAssignment);
+    if (shorthand) return asArrayLiteral(shorthand.getNameNode(), c) ?? null;
+    return null;
+  }
+  return void 0;
+}
+function propInit(entry, name) {
+  return entry.getProperty(name)?.asKind(SyntaxKind4.PropertyAssignment)?.getInitializer();
+}
+var feeAllocationShape = (c, p) => {
+  const calls = c.fn.getDescendantsOfKind(SyntaxKind4.CallExpression).filter((x) => callName2(x) === p.configCall);
+  if (calls.length === 0) return { result: "fail", detail: p.absentDetail };
+  const arr = feeArray(calls[0], p.arrayProp, c);
+  if (arr === void 0 || arr === null) {
+    return { result: "cant_tell", detail: p.dynamicDetail };
+  }
+  const entries = arr.getElements().map((e) => e.asKind(SyntaxKind4.ObjectLiteralExpression));
+  if (entries.length === 0 || entries.some((e) => !e)) {
+    return { result: "cant_tell", detail: p.dynamicDetail };
+  }
+  const creatorParam = c.params.find((name) => new RegExp(p.creatorParamRegex, "i").test(name));
+  const creatorIncluded = creatorParam ? entries.some((e) => propInit(e, p.walletProp)?.getText() === creatorParam) : false;
+  if (!creatorIncluded) return { result: "fail", detail: p.creatorMissingDetail };
+  let sum = 0;
+  let allNumeric = true;
+  for (const e of entries) {
+    const lit = propInit(e, p.bpsProp)?.asKind(SyntaxKind4.NumericLiteral);
+    if (!lit) {
+      allNumeric = false;
+      break;
+    }
+    sum += Number(lit.getLiteralValue());
+  }
+  if (!allNumeric) return { result: "cant_tell", detail: p.dynamicDetail };
+  if (sum !== p.bpsTotal) {
+    return { result: "fail", detail: String(p.bpsSumDetail).replace("{sum}", String(sum)) };
+  }
+  return { result: "pass", detail: String(p.passDetail).replace("{param}", creatorParam) };
+};
+
+// src/checkers/index.ts
+var registry = {
+  "positional-arg-identity": positionalArgIdentity,
+  "required-call-with-options": requiredCallWithOptions,
+  "fee-allocation-shape": feeAllocationShape
+};
+function runChecker(kind, c, params) {
+  const fn = registry[kind];
+  if (!fn) return { result: "cant_tell", detail: `Unknown checker kind '${kind}'.` };
+  return fn(c, params);
+}
+var checkerKinds = Object.keys(registry);
+
+// src/emit.ts
+function buildReport(target, checks, rules2) {
+  const byId = new Map(rules2.map((r) => [r.id, r]));
+  const checkTotals = { pass: 0, fail: 0, cant_tell: 0 };
+  for (const c of checks) checkTotals[c.result]++;
+  const riskTotals = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const c of checks) if (c.result === "fail") riskTotals[c.severity]++;
+  const ruleIdsSeen = [...new Set(checks.map((c) => c.ruleId))];
+  const components = ruleIdsSeen.map((id) => {
+    const rule = byId.get(id);
+    const fails = checks.filter((c) => c.ruleId === id && c.result === "fail");
+    return {
+      name: rule?.component.name ?? id,
+      type: rule?.component.type ?? "Other",
+      version: rule?.component.version ?? "unversioned",
+      sourceUrl: rule?.component.sourceUrl ?? null,
+      status: "fresh",
+      risks: fails.map((c) => ({ severity: c.severity, title: c.title, detail: c.detail }))
+    };
+  });
+  const now = /* @__PURE__ */ new Date();
+  const totalFails = checkTotals.fail;
+  return {
+    schemaVersion: "1.0",
+    run: {
+      id: now.toISOString().replace(/[-:T]/g, "").slice(0, 14),
+      date: now.toISOString().slice(0, 10),
+      requirements: `Catastrophic-integration audit of ${target}`,
+      generator: "@brainblast/core"
+    },
+    summary: {
+      building: "external integrations",
+      verdict: totalFails > 0 ? "blocked" : "ready",
+      topRisk: totalFails > 0 ? checks.find((c) => c.result === "fail")?.detail ?? null : null,
+      mustDecideFirst: null,
+      watchOutFor: null
+    },
+    components,
+    riskTotals,
+    checks: checks.map((c) => ({
+      ruleId: c.ruleId,
+      severity: c.severity,
+      result: c.result,
+      file: c.file,
+      line: c.line,
+      title: c.title,
+      detail: c.detail
+    })),
+    checkTotals,
+    openQuestions: []
+  };
+}
+
+// src/audit.ts
+function auditWithRule(targetDir, rule) {
+  return findCandidates(targetDir, rule).map((c) => {
+    const outcome = runChecker(rule.check.kind, c, rule.check.params);
+    return {
+      ruleId: rule.id,
+      severity: rule.severity,
+      title: rule.title,
+      file: c.filePath,
+      line: c.fn.getStartLineNumber(),
+      exportName: c.fnName,
+      ...outcome
+    };
+  });
+}
+function audit(targetDir, rules2) {
+  const checks = rules2.flatMap((r) => auditWithRule(targetDir, r));
+  const report = buildReport(targetDir, checks, rules2);
+  return { checks, report };
+}
+
+// src/testTemplates/stripeWebhookSignature.ts
+var stripeWebhookSignature = ({ handlerImportPath, handlerExport }) => `// GENERATED by @brainblast/core. Durable guardrail \u2014 RED until the webhook
+// verifies the signature on the RAW body.
+import { describe, it, expect, beforeAll } from "vitest";
+import Stripe from "stripe";
+import { ${handlerExport} } from ${JSON.stringify(handlerImportPath)};
+
+const SECRET = "whsec_brainblast_test_secret";
+const stripe = new Stripe("sk_test_brainblast");
+const payload = JSON.stringify({ id: "evt_1", type: "payment_intent.succeeded", data: { object: { id: "pi_1" } } });
+
+beforeAll(() => {
+  process.env.STRIPE_WEBHOOK_SECRET = SECRET;
+  process.env.STRIPE_SECRET_KEY = "sk_test_brainblast";
+});
+
+describe("Stripe webhook signature verification (brainblast contract)", () => {
+  it("accepts a validly-signed event", () => {
+    const sig = stripe.webhooks.generateTestHeaderString({ payload, secret: SECRET });
+    expect(() => ${handlerExport}(payload, sig)).not.toThrow();
+  });
+  it("REJECTS an invalid signature (forged event)", () => {
+    expect(() => ${handlerExport}(payload, "t=1,v1=deadbeef")).toThrow();
+  });
+  it("REJECTS a mutated body under a valid-looking signature", () => {
+    const sig = stripe.webhooks.generateTestHeaderString({ payload, secret: SECRET });
+    const mutated = payload.replace("succeeded", "failed");
+    expect(() => ${handlerExport}(mutated, sig)).toThrow();
+  });
+});
+`;
+
+// src/testTemplates/privyJwtClaims.ts
+var privyJwtClaims = ({ handlerImportPath, handlerExport }) => `// GENERATED by @brainblast/core. Durable guardrail \u2014 RED until the token is
+// verified (signature + aud + iss).
+import { describe, it, expect, beforeAll } from "vitest";
+import { SignJWT, generateKeyPair, exportSPKI } from "jose";
+import { ${handlerExport} } from ${JSON.stringify(handlerImportPath)};
+
+const APP_ID = "app_brainblast";
+let valid = "", badSignature = "", wrongAudience = "", wrongIssuer = "";
+
+beforeAll(async () => {
+  const { publicKey, privateKey } = await generateKeyPair("ES256");
+  const attacker = await generateKeyPair("ES256");
+  process.env.PRIVY_APP_ID = APP_ID;
+  process.env.PRIVY_VERIFICATION_KEY = await exportSPKI(publicKey);
+
+  const mint = (signer: any, iss: string, aud: string) =>
+    new SignJWT({})
+      .setProtectedHeader({ alg: "ES256" })
+      .setIssuer(iss)
+      .setAudience(aud)
+      .setSubject("did:privy:user_1")
+      .setExpirationTime("1h")
+      .sign(signer);
+
+  valid = await mint(privateKey, "privy.io", APP_ID);
+  badSignature = await mint(attacker.privateKey, "privy.io", APP_ID);
+  wrongAudience = await mint(privateKey, "privy.io", "app_evil");
+  wrongIssuer = await mint(privateKey, "evil.com", APP_ID);
+});
+
+const call = (t: string) => Promise.resolve().then(() => ${handlerExport}(t));
+
+describe("Privy access-token verification (brainblast contract)", () => {
+  it("accepts a valid token", async () => { await expect(call(valid)).resolves.toBeDefined(); });
+  it("REJECTS a bad signature (forged token)", async () => { await expect(call(badSignature)).rejects.toThrow(); });
+  it("REJECTS a wrong audience (token from another app)", async () => { await expect(call(wrongAudience)).rejects.toThrow(); });
+  it("REJECTS a wrong issuer", async () => { await expect(call(wrongIssuer)).rejects.toThrow(); });
+});
+`;
+
+// src/testTemplates/bagsFeeShare.ts
+var bagsFeeShare = ({ handlerImportPath, handlerExport }) => `// GENERATED by @brainblast/core. Durable guardrail \u2014 RED until the fee-share
+// config includes the creator wallet with a non-zero userBps summing to 10000.
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+let captured: any;
+vi.mock("@bagsfm/bags-sdk", () => ({
+  createBagsFeeShareConfig: (cfg: any) => {
+    captured = cfg;
+    return { meteoraConfigKey: "mock-config-key" };
+  },
+  BagsSDK: class {},
+}));
+
+import { ${handlerExport} } from ${JSON.stringify(handlerImportPath)};
+
+const CREATOR = "CreatorWa11etPubKey1111111111111111111111111";
+
+describe("Bags fee-share creator inclusion (brainblast contract)", () => {
+  beforeEach(() => {
+    captured = undefined;
+  });
+
+  it("passes the creator wallet into feeClaimers", () => {
+    ${handlerExport}(CREATOR);
+    const claimers = captured?.feeClaimers ?? [];
+    expect(claimers.some((c: any) => c.user === CREATOR)).toBe(true);
+  });
+
+  it("allocates the creator a non-zero userBps", () => {
+    ${handlerExport}(CREATOR);
+    const entry = (captured?.feeClaimers ?? []).find((c: any) => c.user === CREATOR);
+    expect(entry?.userBps ?? 0).toBeGreaterThan(0);
+  });
+
+  it("feeClaimers userBps sum to exactly 10000", () => {
+    ${handlerExport}(CREATOR);
+    const sum = (captured?.feeClaimers ?? []).reduce((s: number, c: any) => s + c.userBps, 0);
+    expect(sum).toBe(10000);
+  });
+});
+`;
+
+// src/testTemplates/index.ts
+var registry2 = {
+  "stripe-webhook-signature": stripeWebhookSignature,
+  "privy-jwt-claims": privyJwtClaims,
+  "bags-fee-share": bagsFeeShare
+};
+var JS_IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+function renderTest(kind, opts) {
+  const tpl = registry2[kind];
+  if (!tpl) throw new Error(`Unknown test template kind '${kind}'.`);
+  if (!JS_IDENTIFIER.test(opts.handlerExport)) {
+    throw new Error(`Unsafe handler export name '${opts.handlerExport}' (not a JS identifier).`);
+  }
+  return tpl(opts);
+}
+var testKinds = Object.keys(registry2);
+
+// src/loadRules.ts
+import { readdirSync as readdirSync2, readFileSync } from "fs";
+import { join as join2 } from "path";
+import { parse } from "yaml";
+var SEVERITIES = ["critical", "high", "medium", "low"];
+function validateRule(r, file) {
+  const errs = [];
+  if (!r || typeof r !== "object") {
+    throw new Error(`invalid rule in ${file}: not a mapping`);
+  }
+  if (!r.id || typeof r.id !== "string") errs.push("missing id");
+  if (!SEVERITIES.includes(r.severity)) errs.push(`bad severity '${r.severity}'`);
+  if (!r.title || typeof r.title !== "string") errs.push("missing title");
+  if (!r.component || !r.component.name || !r.component.type) errs.push("missing component.name/type");
+  if (!r.detect || !Array.isArray(r.detect.modules) || typeof r.detect.nameRegex !== "string" || !Array.isArray(r.detect.triggerCalls)) {
+    errs.push("detect must have modules[], nameRegex (string), triggerCalls[]");
+  } else {
+    try {
+      new RegExp(r.detect.nameRegex);
+    } catch {
+      errs.push(`detect.nameRegex is not a valid regex: ${r.detect.nameRegex}`);
+    }
+  }
+  if (!r.check || !checkerKinds.includes(r.check.kind)) {
+    errs.push(`check.kind must be one of ${checkerKinds.join("|")} (got '${r.check?.kind}')`);
+  }
+  if (!r.test || !testKinds.includes(r.test.kind)) {
+    errs.push(`test.kind must be one of ${testKinds.join("|")} (got '${r.test?.kind}')`);
+  }
+  if (errs.length) throw new Error(`invalid rule in ${file}: ${errs.join("; ")}`);
+}
+function loadRules(dir) {
+  const files = readdirSync2(dir).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml")).sort();
+  const rules2 = [];
+  for (const f of files) {
+    const raw = parse(readFileSync(join2(dir, f), "utf8"));
+    validateRule(raw, f);
+    rules2.push(raw);
+  }
+  return rules2;
+}
+
+// rules/index.ts
+import { existsSync } from "fs";
+import { dirname, join as join3 } from "path";
+import { fileURLToPath } from "url";
+function bundledRulesDir() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  if (existsSync(join3(here, "stripe-webhook-raw-body.yaml"))) return here;
+  const sub = join3(here, "rules");
+  if (existsSync(join3(sub, "stripe-webhook-raw-body.yaml"))) return sub;
+  return here;
+}
+var rules = loadRules(bundledRulesDir());
+
+// src/resolveRules.ts
+import { existsSync as existsSync2 } from "fs";
+import { join as join4 } from "path";
+function resolveRules(targetDir) {
+  const all = [...rules];
+  const projDir = join4(targetDir, ".agent-research", "rules");
+  if (existsSync2(projDir)) {
+    const seen = new Set(all.map((r) => r.id));
+    for (const r of loadRules(projDir)) {
+      if (seen.has(r.id)) {
+        console.warn(`brainblast: project rule '${r.id}' shadows a bundled rule; keeping bundled.`);
+        continue;
+      }
+      all.push(r);
+      seen.add(r.id);
+    }
+  }
+  return all;
+}
+
+export {
+  findCandidates,
+  runChecker,
+  checkerKinds,
+  auditWithRule,
+  audit,
+  renderTest,
+  testKinds,
+  loadRules,
+  rules,
+  resolveRules
+};

package/dist/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import {
+  audit,
+  resolveRules
+} from "./chunk-H2Y75CSH.js";
+
+// src/cli.ts
+import { writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+var args = process.argv.slice(2);
+var ci = args.includes("--ci");
+var strict = args.includes("--strict");
+var targetDir = args.find((a) => !a.startsWith("--")) ?? process.cwd();
+var rules = resolveRules(targetDir);
+var { checks, report } = audit(targetDir, rules);
+var outDir = join(targetDir, ".agent-research");
+mkdirSync(outDir, { recursive: true });
+var reportPath = join(outDir, "report.json");
+writeFileSync(reportPath, JSON.stringify(report, null, 2));
+console.log(`brainblast: scanned ${targetDir} with ${rules.length} rule(s)`);
+if (checks.length === 0) console.log("  (no catastrophic components detected)");
+for (const c of checks) {
+  const tag = c.result === "pass" ? "PASS " : c.result === "fail" ? "FAIL " : "WARN ";
+  console.log(`  [${tag}] ${c.ruleId}  ${c.file}:${c.line}`);
+  console.log(`          ${c.detail}`);
+}
+var fails = checks.filter((c) => c.result === "fail").length;
+var cantTell = checks.filter((c) => c.result === "cant_tell").length;
+console.log(`  verdict: ${report.summary.verdict}  (fail=${fails}, cant_tell=${cantTell})`);
+if (cantTell > 0 && !strict) {
+  console.log(`  warning: ${cantTell} cant_tell (not gating \u2014 pass --strict to fail on these)`);
+}
+console.log(`  report:  ${reportPath}`);
+if (ci) {
+  const gateFail = fails > 0 || strict && cantTell > 0;
+  process.exit(gateFail ? 1 : 0);
+}

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+import { FunctionDeclaration, ArrowFunction } from 'ts-morph';
+
+type Severity = "critical" | "high" | "medium" | "low";
+type CheckResultKind = "pass" | "fail" | "cant_tell";
+interface Candidate {
+    filePath: string;
+    fnName: string;
+    params: string[];
+    fn: FunctionDeclaration | ArrowFunction;
+}
+interface CheckOutcome {
+    result: CheckResultKind;
+    detail: string;
+}
+interface CheckResult extends CheckOutcome {
+    ruleId: string;
+    severity: Severity;
+    title: string;
+    file: string;
+    line: number;
+    exportName: string;
+}
+interface Rule {
+    id: string;
+    severity: Severity;
+    title: string;
+    component: {
+        name: string;
+        type: string;
+        version?: string;
+        sourceUrl?: string;
+    };
+    detect: {
+        modules: string[];
+        nameRegex: string;
+        triggerCalls: string[];
+    };
+    check: {
+        kind: string;
+        params: Record<string, any>;
+    };
+    test: {
+        kind: string;
+        params?: Record<string, any>;
+    };
+}
+
+declare function auditWithRule(targetDir: string, rule: Rule): CheckResult[];
+declare function audit(targetDir: string, rules: Rule[]): {
+    checks: CheckResult[];
+    report: {
+        schemaVersion: string;
+        run: {
+            id: string;
+            date: string;
+            requirements: string;
+            generator: string;
+        };
+        summary: {
+            building: string;
+            verdict: string;
+            topRisk: string | null;
+            mustDecideFirst: null;
+            watchOutFor: null;
+        };
+        components: {
+            name: string;
+            type: string;
+            version: string;
+            sourceUrl: string | null;
+            status: string;
+            risks: {
+                severity: Severity;
+                title: string;
+                detail: string;
+            }[];
+        }[];
+        riskTotals: {
+            critical: number;
+            high: number;
+            medium: number;
+            low: number;
+        };
+        checks: {
+            ruleId: string;
+            severity: Severity;
+            result: CheckResultKind;
+            file: string;
+            line: number;
+            title: string;
+            detail: string;
+        }[];
+        checkTotals: {
+            pass: number;
+            fail: number;
+            cant_tell: number;
+        };
+        openQuestions: never[];
+    };
+};
+
+declare function resolveRules(targetDir: string): Rule[];
+
+declare function loadRules(dir: string): Rule[];
+
+declare const rules: Rule[];
+
+declare function generateTestForResult(result: CheckResult, rule: Rule, outPath: string): string;
+
+declare function renderTest(kind: string, opts: {
+    handlerImportPath: string;
+    handlerExport: string;
+    params?: any;
+}): string;
+declare const testKinds: string[];
+
+declare function runChecker(kind: string, c: Candidate, params: any): CheckOutcome;
+declare const checkerKinds: string[];
+
+declare function findCandidates(targetDir: string, rule: Rule): Candidate[];
+
+export { type Candidate, type CheckOutcome, type CheckResult, type CheckResultKind, type Rule, type Severity, audit, auditWithRule, rules as bundledRules, checkerKinds, findCandidates, generateTestForResult, loadRules, renderTest, resolveRules, runChecker, testKinds };

package/dist/index.js

@@ -0,0 +1,39 @@
+import {
+  audit,
+  auditWithRule,
+  checkerKinds,
+  findCandidates,
+  loadRules,
+  renderTest,
+  resolveRules,
+  rules,
+  runChecker,
+  testKinds
+} from "./chunk-H2Y75CSH.js";
+
+// src/generate.ts
+import { writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+function generateTestForResult(result, rule, outPath) {
+  const src = renderTest(rule.test.kind, {
+    handlerImportPath: result.file,
+    handlerExport: result.exportName,
+    params: rule.test.params
+  });
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, src);
+  return outPath;
+}
+export {
+  audit,
+  auditWithRule,
+  rules as bundledRules,
+  checkerKinds,
+  findCandidates,
+  generateTestForResult,
+  loadRules,
+  renderTest,
+  resolveRules,
+  runChecker,
+  testKinds
+};

package/dist/rules/bags-fee-share-creator-included.yaml

@@ -0,0 +1,40 @@
+# Pure-data rule (facts). Binds to vetted templates by `check.kind`/`test.kind`.
+id: bags-fee-share-creator-included
+severity: critical
+title: Bags fee-share config includes the creator wallet and BPS sum to 10000
+component:
+  name: Bags Token Launch v2
+  type: API
+  version: unversioned
+  sourceUrl: https://docs.bags.fm/changelog/changelog
+detect:
+  modules: ["@bagsfm/bags-sdk"]
+  nameRegex: "feeshare|feeclaimer|bagsfee|launchtoken|tokenlaunch"
+  triggerCalls: [createBagsFeeShareConfig]
+check:
+  kind: fee-allocation-shape
+  params:
+    configCall: createBagsFeeShareConfig
+    arrayProp: feeClaimers
+    walletProp: user
+    bpsProp: userBps
+    bpsTotal: 10000
+    creatorParamRegex: "creator"
+    absentDetail: >-
+      No createBagsFeeShareConfig call in the builder. Token Launch v2 requires a
+      fee-share config for every launch; without one the launch cannot proceed.
+    dynamicDetail: >-
+      feeClaimers is assembled dynamically (variable, spread, or .map), so creator
+      inclusion and the 10000-BPS total can't be confirmed statically. Verify by
+      hand that the creator wallet is present with a non-zero userBps.
+    creatorMissingDetail: >-
+      The creator wallet is not in feeClaimers. The creator must be an explicit
+      entry — omitting them does NOT default them to any share; they earn zero
+      fees forever, and the fee config is immutable on-chain after launch.
+    bpsSumDetail: >-
+      feeClaimers userBps sum to {sum}, not 10000. Bags requires the allocation to
+      total exactly 10000 (100%); a mismatch is rejected at config creation.
+    passDetail: >-
+      Creator wallet '{param}' is an explicit feeClaimers entry and userBps sum to 10000.
+test:
+  kind: bags-fee-share

package/dist/rules/privy-jwt-verification.yaml

@@ -0,0 +1,30 @@
+# Pure-data rule (facts). Binds to vetted templates by `check.kind`/`test.kind`.
+id: privy-jwt-verification
+severity: critical
+title: Privy access token verified (signature + aud + iss)
+component:
+  name: Privy auth
+  type: Auth
+  version: unversioned
+  sourceUrl: https://docs.privy.io/authentication/user-authentication/access-tokens
+detect:
+  modules: [jose, jsonwebtoken, "@privy-io/node", "@privy-io/server-auth"]
+  nameRegex: "token|auth|verify|privy|jwt"
+  triggerCalls: [decodeJwt, jwtVerify, verify, decode]
+check:
+  kind: required-call-with-options
+  params:
+    verifyCalls: [jwtVerify, verify]
+    decodeCalls: [decodeJwt, decode]
+    requiredProps:
+      - [audience, aud]
+      - [issuer, iss]
+    passDetail: Token signature is verified and both aud and iss are asserted.
+    missingPropsDetail: >-
+      Token signature is verified but aud/iss are not asserted. A valid token
+      from another Privy app is accepted.
+    decodeOnlyDetail: >-
+      Token is decoded without verifying its signature. Any forged token is
+      accepted — auth bypass.
+test:
+  kind: privy-jwt-claims

package/dist/rules/stripe-webhook-raw-body.yaml

@@ -0,0 +1,28 @@
+# Pure-data rule (facts). Binds to vetted templates by `check.kind`/`test.kind`.
+id: stripe-webhook-raw-body-verification
+severity: critical
+title: Stripe webhook signature verified on the raw body
+component:
+  name: Stripe webhook
+  type: API
+  version: unversioned
+  sourceUrl: https://docs.stripe.com/webhooks/signature
+detect:
+  modules: [stripe]
+  nameRegex: webhook
+  triggerCalls: [constructEvent]
+check:
+  kind: positional-arg-identity
+  params:
+    call: constructEvent
+    argIndex: 0
+    paramIndex: 0
+    absentDetail: >-
+      No stripe.webhooks.constructEvent call in the handler. Signatures are not
+      verified; forged 'payment_intent.succeeded' events are accepted.
+    parsedDetail: >-
+      constructEvent is called on a parsed/derived value, not the raw request
+      body. Verification is bypassed.
+    passDetail: constructEvent verifies the raw body parameter '{param}'.
+test:
+  kind: stripe-webhook-signature

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "brainblast",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Deterministic auditor for catastrophic AI-integration bugs: scan a repo, find the silent money/auth traps, and generate the behavioral test that proves they're fixed.",
+  "keywords": ["security", "static-analysis", "stripe", "webhook", "jwt", "solana", "bags", "ci", "ai", "audit"],
+  "license": "MIT",
+  "author": "DSB-117",
+  "homepage": "https://github.com/DSB-117/brainblast/tree/main/packages/core#readme",
+  "bugs": { "url": "https://github.com/DSB-117/brainblast/issues" },
+  "repository": { "type": "git", "url": "git+https://github.com/DSB-117/brainblast.git", "directory": "packages/core" },
+  "bin": { "brainblast": "dist/cli.js" },
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+  },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=18" },
+  "publishConfig": { "access": "public", "provenance": true },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "audit": "tsx src/cli.ts",
+    "prove": "tsx scripts/prove.ts",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "ts-morph": "^23",
+    "yaml": "^2"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^2",
+    "jose": "^5",
+    "stripe": "^17",
+    "tsup": "^8",
+    "tsx": "^4",
+    "typescript": "^5",
+    "vitest": "^2"
+  }
+}