brainblast 0.2.0 → 0.4.0

package/dist/programs/directory.yaml

@@ -0,0 +1,179 @@
+# Curated Solana program directory. Human-authored facts; never LLM-edited in
+# place. Every entry is a program brainblast considers "known enough to
+# describe without an RPC call." For anything not in this file, the
+# trust-graph builder falls back to live RPC probing for upgrade authority and
+# reports verifiedBuild=unknown / audits=[] unless the research skill
+# enriches it.
+#
+# Add an entry only when you can cite a primary source for every field.
+# Comments above each entry name those sources.
+
+programs:
+  # System Program — owns wallets, transfers SOL, allocates accounts. Core
+  # runtime; not an upgradeable program. https://docs.solana.com/runtime/programs
+  - programId: "11111111111111111111111111111111"
+    name: System Program
+    kind: runtime
+    upgradeAuthority:
+      kind: renounced
+      address: null
+      source: directory
+    verifiedBuild:
+      state: verified
+      registryUrl: https://github.com/anza-xyz/agave
+    audits: []
+    parity:
+      mainnet: present
+      devnet: present
+      testnet: present
+      notes: Identical on every cluster; part of the validator binary.
+
+  # SPL Token — the legacy SPL token program. Native, non-upgradeable.
+  # https://spl.solana.com/token
+  - programId: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
+    name: SPL Token
+    kind: token
+    upgradeAuthority:
+      kind: renounced
+      address: null
+      source: directory
+    verifiedBuild:
+      state: verified
+      registryUrl: https://github.com/solana-program/token
+    audits:
+      - firm: Kudelski Security
+        date: "2020-08-01"
+        reportUrl: https://github.com/solana-program/token/tree/main/audits
+    parity:
+      mainnet: present
+      devnet: present
+      testnet: present
+      notes: Same address everywhere. Distinct from Token-2022; consumers must pick one and never mix.
+
+  # SPL Token-2022 — the new token program with transfer hooks, fees, and
+  # confidential transfers. DIFFERENT program id from legacy Token; mixing the
+  # two is the #1 trap in the deep-dive research.
+  # https://spl.solana.com/token-2022
+  - programId: "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"
+    name: SPL Token-2022
+    kind: token
+    upgradeAuthority:
+      kind: multisig
+      address: "9YBjtad6ZxR7hxNXyTjRRPnPipFbuAU6c2EVHTSVTQAW"
+      source: directory
+      checkedAt: "2025-04-15"
+    verifiedBuild:
+      state: verified
+      registryUrl: https://github.com/solana-program/token-2022
+    audits:
+      - firm: OtterSec
+        date: "2024-02-01"
+        reportUrl: https://github.com/solana-program/token-2022/tree/main/audits
+    parity:
+      mainnet: present
+      devnet: present
+      testnet: present
+      notes: >-
+        Same address on every cluster. Behavior identical, but extensions like transfer-fee
+        and transfer-hook can encode mainnet-only economics that don't show up in devnet
+        testing of a fresh mint.
+
+  # Metaplex Token Metadata. The metadata account for every NFT and most
+  # SPL-token branding goes through this program. isMutable / collection
+  # verification are immutable-after-mint decisions worth flagging.
+  # https://developers.metaplex.com/token-metadata
+  - programId: "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s"
+    name: Metaplex Token Metadata
+    kind: metadata
+    upgradeAuthority:
+      kind: multisig
+      address: "BFV9MAfDjT8azkAArh9k4iAjwboTBA9z3PNK7BFNKaiK"
+      source: directory
+      checkedAt: "2025-04-15"
+    verifiedBuild:
+      state: verified
+      registryUrl: https://github.com/metaplex-foundation/mpl-token-metadata
+    audits:
+      - firm: OtterSec
+        date: "2023-09-01"
+        reportUrl: https://github.com/metaplex-foundation/mpl-token-metadata/tree/main/programs/token-metadata/audits
+    parity:
+      mainnet: present
+      devnet: present
+      testnet: present
+      notes: Same address everywhere; metadata is the standard NFT/token-info layer.
+
+  # Memo Program. Lets transactions include UTF-8 notes; no state. Useful in
+  # CPI but trivially safe.
+  - programId: "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr"
+    name: SPL Memo
+    kind: utility
+    upgradeAuthority:
+      kind: renounced
+      address: null
+      source: directory
+    verifiedBuild:
+      state: verified
+      registryUrl: https://github.com/solana-program/memo
+    audits: []
+    parity:
+      mainnet: present
+      devnet: present
+      testnet: present
+
+  # Compute Budget Program. Lets a tx set its compute unit price/limit. Pure
+  # runtime; not upgradeable. Worth knowing for fee posture in the cost report.
+  - programId: "ComputeBudget111111111111111111111111111111"
+    name: Compute Budget Program
+    kind: runtime
+    upgradeAuthority:
+      kind: renounced
+      address: null
+      source: directory
+    verifiedBuild:
+      state: verified
+      registryUrl: https://github.com/anza-xyz/agave
+    audits: []
+    parity:
+      mainnet: present
+      devnet: present
+      testnet: present
+
+  # Address Lookup Table Program. Lets transactions reference more accounts
+  # than the legacy 32-account limit allows.
+  - programId: "AddressLookupTab1e1111111111111111111111111"
+    name: Address Lookup Table Program
+    kind: runtime
+    upgradeAuthority:
+      kind: renounced
+      address: null
+      source: directory
+    verifiedBuild:
+      state: verified
+      registryUrl: https://github.com/anza-xyz/agave
+    audits: []
+    parity:
+      mainnet: present
+      devnet: present
+      testnet: present
+
+  # BPF Upgradeable Loader. The program that owns every upgradeable program;
+  # `setAuthority` and `upgrade` instructions go through here. The trust
+  # graph routinely reads ProgramData accounts owned by this address to
+  # resolve the upgrade authority of any other upgradeable program.
+  - programId: "BPFLoaderUpgradeab1e11111111111111111111111"
+    name: BPF Upgradeable Loader
+    kind: loader
+    upgradeAuthority:
+      kind: renounced
+      address: null
+      source: directory
+    verifiedBuild:
+      state: verified
+      registryUrl: https://github.com/anza-xyz/agave
+    audits: []
+    parity:
+      mainnet: present
+      devnet: present
+      testnet: present
+      notes: The loader itself is part of the validator and not upgradeable in the BPF sense.

package/dist/rules/anchor-init-if-needed-guarded.yaml

@@ -0,0 +1,47 @@
+# Pure-data rule (facts). Binds to vetted templates by `check.kind`/`test.kind`.
+# Promoted from findings/anchor-init-if-needed-reinit.json after the
+# proof-as-classifier loop (synth-prove) closed RED->GREEN against the
+# new `anchor-init-if-needed-guarded` checker kind (tree-sitter-rust based).
+id: anchor-init-if-needed-guarded
+severity: critical
+title: Anchor init_if_needed account has a reinitialization guard
+component:
+  name: Anchor Framework
+  type: Blockchain
+  version: ">=0.26.0"
+  sourceUrl: https://www.anchor-lang.com/docs/the-accounts-struct#init_if_needed
+detect:
+  # This rule operates on Rust source files — requires tree-sitter-rust.
+  lang: rust
+  modules:
+    - "@coral-xyz/anchor"
+    - "@project-serum/anchor"
+  # Match instruction handlers that initialize accounts. Detection also
+  # triggers on any function whose Accounts struct has init_if_needed.
+  nameRegex: "initialize|init_if_needed"
+  triggerCalls:
+    - init_if_needed
+check:
+  kind: anchor-init-if-needed-guarded
+  params:
+    passDetail: >-
+      Handler has #[account(init_if_needed)] and a reinitialization guard
+      (require!, data_is_empty, or is_initialized check). A second invocation
+      will be rejected before writing to the account.
+    failAbsentDetail: >-
+      Handler uses #[account(init_if_needed)] without a reinitialization guard.
+      A malicious caller can invoke the instruction a second time to overwrite
+      the account's data — a full state-wipe with no on-chain recourse.
+      Add: require!(account_field.field == initial_value, ErrorCode::AlreadyInitialized)
+      at the top of the handler body.
+    absentDetail: >-
+      Handler has no #[account(init_if_needed)] fields; the reinit-guard rule
+      does not apply.
+test:
+  kind: anchor-program-test
+  params:
+    scenario: reinit-attempt
+    description: >-
+      Calls the instruction twice on the same account; the second call must
+      fail with AlreadyInitialized (or equivalent). If it succeeds, the
+      account state has been silently overwritten.

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

@@ -9,7 +9,12 @@ component:
   sourceUrl: https://docs.bags.fm/changelog/changelog
 detect:
   modules: ["@bagsfm/bags-sdk"]
-  nameRegex: "feeshare|feeclaimer|bagsfee|launchtoken|tokenlaunch"
+  # Keep the regex tight to Bags-specific terms; broad terms like
+  # "launchtoken"/"tokenlaunch" cross-matched non-Bags Solana handlers
+  # (e.g. Token-2022 launch helpers) and produced spurious "no Bags fee
+  # config" failures. Bags candidates still resolve via the import or the
+  # createBagsFeeShareConfig trigger call.
+  nameRegex: "feeshare|feeclaimer|bagsfee"
   triggerCalls: [createBagsFeeShareConfig]
 check:
   kind: fee-allocation-shape

package/dist/rules/metaplex-metadata-immutable.yaml

@@ -0,0 +1,55 @@
+# Pure-data rule (facts). Binds to vetted templates by `check.kind`/`test.kind`.
+# Promoted from findings/metaplex-metadata-immutable.json after the
+# proof-as-classifier loop (synth-prove) closed RED->GREEN against the
+# new `object-arg-property-literal-equals` checker kind.
+id: metaplex-metadata-immutable
+severity: critical
+title: Metaplex createV1 called with isMutable false to seal token metadata at mint
+component:
+  name: Metaplex Token Metadata
+  type: Blockchain
+  version: unversioned
+  sourceUrl: https://developers.metaplex.com/token-metadata
+detect:
+  modules: ["@metaplex-foundation/mpl-token-metadata"]
+  # Brand-specific terms only. Bare "token"/"mint" cross-match SPL-token,
+  # Bags, and other handlers. Metaplex candidates still resolve via the
+  # @metaplex-foundation/mpl-token-metadata import or the createV1/createNft
+  # trigger calls.
+  nameRegex: "metaplex|mpl|createNft"
+  triggerCalls: [createV1, createNft, createAndMint, createMetadataAccountV3]
+check:
+  kind: object-arg-property-literal-equals
+  params:
+    call: createV1
+    argIndex: 1
+    propName: isMutable
+    expectedValue: false
+    passDetail: >-
+      createV1 passes isMutable: false — token metadata is permanently sealed
+      at mint time. Name, symbol, and URI cannot be changed regardless of who
+      holds the update authority.
+    failAbsentDetail: >-
+      createV1 omits isMutable (SDK defaults to true). The update authority
+      retains the ability to change the token name, symbol, and URI after mint —
+      permanently. Seal the metadata by passing isMutable: false. There is no
+      on-chain migration path once metadata is minted as mutable.
+    failWrongDetail: >-
+      createV1 passes isMutable: true explicitly. Token metadata will remain
+      mutable after mint — the update authority key becomes a permanent attack
+      surface. Pass isMutable: false to seal it at mint time.
+    failArgDetail: >-
+      createV1's options argument is not an inline object literal; cannot
+      statically verify isMutable. Inline the options object so static analysis
+      can confirm isMutable: false.
+    failDynamicDetail: >-
+      isMutable is set via a variable or expression; cannot confirm it resolves
+      to false statically. Use the boolean literal false directly.
+    absentCallDetail: >-
+      Handler is in Metaplex scope but does not call createV1; the
+      metadata-immutability rule does not apply here.
+    scopeNotMetDetail: >-
+      File does not import from @metaplex-foundation/mpl-token-metadata; the
+      metadata-immutability rule does not apply.
+test:
+  kind: metaplex-immutable-metadata

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

@@ -9,8 +9,24 @@ component:
   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]
+  # Brand-specific terms only. Bare "token"/"auth" cross-match unrelated
+  # Solana handlers (launchToken, etc.) and produce spurious cant_tell noise.
+  # Privy handlers are still picked up by the @privy-io/* / jose / jsonwebtoken
+  # imports, and by triggerCalls like decodeJwt / jwtVerify.
+  nameRegex: "privy|jwt"
+  # Only decodeJwt triggers detection; it's specific to jose and unambiguously
+  # indicates a decode-only pattern.  jwtVerify/verify/decode were removed because:
+  #   - "verify" matches Node.js crypto.verify(), jsonwebtoken jwt.verify(), etc.
+  #   - "decode" matches bs58.decode() (Solana), Buffer.from(), etc.
+  #   - "jwtVerify" matches Fastify's request.jwtVerify() plugin method, which is
+  #     not a jose-based call and requires no audience/issuer options.
+  # Functions that import jose/@privy-io/* and are named with "privy|jwt" are still
+  # detected via requiresImport + (importsModule && hasName), the primary detection path.
+  triggerCalls: [decodeJwt]
+  # A module import is REQUIRED to be a candidate.  Without this guard, a Fastify
+  # middleware named "verifyJwt" (which calls request.jwtVerify(), a completely
+  # different library) would match the nameRegex and be flagged as missing aud/iss.
+  requiresImport: true
 check:
   kind: required-call-with-options
   params:

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

@@ -11,6 +11,11 @@ detect:
   modules: [stripe]
   nameRegex: webhook
   triggerCalls: [constructEvent]
+  # Require the file to import stripe.  Without this guard, any function whose
+  # name contains "webhook" — even LemonSqueezy, Polar, or Sendgrid handlers —
+  # is flagged for missing stripe.webhooks.constructEvent, producing false
+  # positives on non-Stripe payment integrations.
+  requiresImport: true
 check:
   kind: positional-arg-identity
   params:

package/dist/rules/token-2022-program-id-pinned.yaml

@@ -0,0 +1,55 @@
+# Pure-data rule (facts). Binds to vetted templates by `check.kind`/`test.kind`.
+# Promoted from findings/token-2022-program-id-mismatch.json after the
+# proof-as-classifier loop (synth-prove) closed RED->GREEN against the
+# new `arg-equals-constant-identifier` checker kind.
+id: token-2022-program-id-pinned
+severity: critical
+title: Token-2022 createMint passes TOKEN_2022_PROGRAM_ID as the program ID argument
+component:
+  name: SPL Token-2022
+  type: Blockchain
+  version: unversioned
+  sourceUrl: https://spl.solana.com/token-2022
+detect:
+  modules: ["@solana/spl-token"]
+  # Keep the regex narrow to terms specific to SPL-token-mint construction;
+  # bare "token"/"launch" would cross-match unrelated handlers (Privy
+  # verifyPrivyToken, etc.). Real Token-2022 handlers still resolve via the
+  # @solana/spl-token import or the createMint trigger call.
+  nameRegex: "createMint|mint22|token2022"
+  triggerCalls: [createMint]
+check:
+  kind: arg-equals-constant-identifier
+  params:
+    call: createMint
+    argIndex: 7
+    expectedIdentifier: TOKEN_2022_PROGRAM_ID
+    forbiddenIdentifiers: [TOKEN_PROGRAM_ID]
+    # Scope predicate: only enforce when the file imports TOKEN_2022_PROGRAM_ID.
+    # Without this, every legacy-mint codebase would false-positive.
+    requireImport: TOKEN_2022_PROGRAM_ID
+    passDetail: >-
+      createMint passes {expected} as its programId argument — Token-2022
+      features will work as designed.
+    failForbiddenDetail: >-
+      createMint passes {got} (legacy Token program) where Token-2022 was
+      intended. The mint will be owned by the legacy program; Token-2022
+      features (transfer hooks, transfer fees, confidential transfers) will
+      not work and there is NO on-chain fix — a mint's owner program is part
+      of its identity.
+    failMissingDetail: >-
+      createMint omits its programId argument (or passes undefined), which
+      silently defaults to the LEGACY Token program even though the file
+      imports {expected}. Pass {expected} explicitly.
+    failOtherDetail: >-
+      createMint passes '{got}' as programId; expected {expected}. If this is
+      a custom constant, alias it to {expected} or pass the canonical name so
+      the trap detector and downstream readers agree.
+    absentCallDetail: >-
+      Handler is in the SPL-token scope but does not call createMint; the
+      Token-2022 pin rule does not apply here.
+    scopeNotMetDetail: >-
+      File does not import TOKEN_2022_PROGRAM_ID; legacy-token codebase — the
+      Token-2022 pin rule does not apply.
+test:
+  kind: token-program-consistency

package/package.json

@@ -1,35 +1,76 @@
 {
   "name": "brainblast",
-  "version": "0.2.0",
+  "version": "0.4.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"],
+  "keywords": [
+    "security",
+    "static-analysis",
+    "audit",
+    "stripe",
+    "webhook",
+    "jwt",
+    "solana",
+    "anchor",
+    "metaplex",
+    "token-2022",
+    "trust-graph",
+    "bags",
+    "rent",
+    "ci",
+    "ai"
+  ],
   "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" },
+  "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" }
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
   },
-  "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",
+    "synth": "tsx scripts/synth-prove.ts",
+    "synth:bags": "tsx scripts/synth-prove.ts findings/bags-known-answer.json",
     "test": "vitest run",
     "coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
+    "tree-sitter": "^0.22.4",
+    "tree-sitter-rust": "^0.24.0",
     "ts-morph": "^23",
     "yaml": "^2"
   },
   "devDependencies": {
+    "@metaplex-foundation/mpl-token-metadata": "^3.4.0",
+    "@solana/spl-token": "^0.4.14",
     "@types/node": "^22",
     "@vitest/coverage-v8": "^2",
     "jose": "^5",