seamshield 0.2.0 → 0.2.2

package/README.md

@@ -5,6 +5,12 @@ Local access-lane security scanner for AI-built JavaScript and TypeScript apps.
 SeamShield maps who or what can reach sensitive assets before you ship:
 `Actor -> Lane -> Asset -> Permission -> Condition -> Risk`.
 
+The CLI is the open-source local scanner/control engine. Run it locally,
+inspect it, block network access, and verify source code does not leave your
+machine. Commercial SeamShield layers such as premium rulepacks, dashboards,
+signed rule distribution, suppression approvals, audit trails, and managed
+policy workflows are outside this npm package.
+
 ## Install
 
 ```bash
@@ -27,7 +33,9 @@ seamshield ship .
 seamshield access . --format table
 seamshield access . --format json
 seamshield scan . --offline
+seamshield investigate .
 seamshield fix-plan . --agent codex
+seamshield agent-context . --codex
 seamshield triage . --rule ss/auth/client-only-guard
 seamshield agent-context . --claude
 seamshield agent-context . --cursor
@@ -42,7 +50,11 @@ seamshield ship .
 ```
 
 Runs locally and prints `SAFE TO SHIP` only when there are no block or high
-access-lane risks. Use this before deploys.
+unsafe-to-ship access-lane risks found by the controls that ran. Use this
+before deploys; it does not replace a security review.
+
+By default, `ship` also writes a Markdown investigation under
+`.seamshield/investigations/` so new repos have a durable review artifact.
 
 ## Access Map
 
@@ -55,6 +67,11 @@ Supported surfaces include Next.js/API routes, Supabase, Firebase/Firestore,
 Convex, Vercel/Coolify/self-hosted deploy config, generic Node servers, AI
 agent config, and package supply-chain risks.
 
+Convex coverage includes public function checks for sensitive queries,
+mutations, and actions without recognized auth/internal guards. Vercel coverage
+includes `vercel.json` public env secrets, wildcard credentialed CORS, and
+public privileged route/cron surfaces.
+
 ## Scan
 
 ```bash
@@ -63,6 +80,7 @@ seamshield scan . --format json
 seamshield scan . --format sarif
 seamshield scan . --fail-on high
 seamshield scan . --offline
+seamshield scan . --no-investigation
 ```
 
 Exit codes:
@@ -73,6 +91,20 @@ Exit codes:
 
 `--offline` disables npm registry and OSV checks. Static rules still run.
 
+By default, `scan` writes `.seamshield/investigations/<date>-access-lanes.md`
+and prints the path to stderr so JSON/SARIF stdout remains parseable. Use
+`--no-investigation` for CI jobs that should not write files.
+
+## Investigations
+
+```bash
+seamshield investigate .
+```
+
+Writes a Markdown investigation summarizing the ship verdict, severity/provider
+breakdowns, normalized access lanes, and suggested next commands. This is meant
+to make findings understandable in a fresh repo without uploading source code.
+
 ## Triage
 
 ```bash
@@ -98,15 +130,19 @@ Writes `.seamshield/fix-plan.json` and a Markdown plan under
 ## Agent Guard
 
 ```bash
+seamshield agent-context . --codex
 seamshield agent-context . --claude
 seamshield agent-context . --cursor
 seamshield guard install .
 ```
 
-`agent-context` writes agent instructions. `guard install` adds a Claude Code
-`PreToolUse` hook that blocks high-confidence risky edits such as committed
-dotenv files, exposed server secrets, public database/storage writes, unsafe
-`.env` edits, dangerous shell installs, and obvious privileged route exposure.
+`agent-context --codex` writes `AGENTS.md`. `--claude` writes `CLAUDE.md`.
+`--cursor` writes `.cursor/rules/seamshield.mdc`.
+
+`guard install` adds a Claude Code `PreToolUse` hook that blocks
+high-confidence risky edits such as committed dotenv files, exposed server
+secrets, public database/storage writes, unsafe `.env` edits, dangerous shell
+installs, and obvious privileged route exposure.
 
 Guard behavior is fail-open: if the hook errors, it allows the tool call and
 appends diagnostics to `.seamshield/guard.log`.
@@ -145,3 +181,19 @@ run fully local.
 
 Secret evidence is redacted before findings, JSON, SARIF, and fix plans are
 emitted.
+
+`learn` is currently a no-upload stub. SeamShield does not auto-update or run
+untrusted community rules.
+
+## Release Trust
+
+Install from the official npm package:
+
+```bash
+npx seamshield ship .
+npm install -g seamshield
+```
+
+For release audits, use npm tarball integrity/checksum metadata and prefer the
+documented package entrypoint over forks or republished packages. Signed
+rulepack distribution is reserved for a future commercial/control-plane layer.

package/dist/index.js

@@ -100,9 +100,9 @@ var require_picocolors = __commonJS({
 
 // src/index.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync2, mkdirSync as mkdirSync3, mkdtempSync, readFileSync as readFileSync6, rmSync, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync2, mkdirSync as mkdirSync4, mkdtempSync, readFileSync as readFileSync6, rmSync, writeFileSync as writeFileSync4 } from "fs";
 import { tmpdir } from "os";
-import { dirname as dirname3, join as join7, resolve as resolve2 } from "path";
+import { dirname as dirname3, join as join8, resolve as resolve2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command } from "commander";
 import { parse as parse3, stringify } from "yaml";
@@ -120,9 +120,11 @@ import { spawnSync } from "child_process";
 import { basename as basename2 } from "path";
 import { mkdirSync, writeFileSync } from "fs";
 import { join as join22 } from "path";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join3 } from "path";
 import { createHash } from "crypto";
 import { readFileSync as readFileSync2, readdirSync } from "fs";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 import { parse as parse2 } from "yaml";
 import { z as z2 } from "zod";
 import { readFileSync as readFileSync5 } from "fs";
@@ -140,12 +142,13 @@ var findingSchemaPath = join(
 );
 
 // ../core/dist/index.js
-import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname2, join as join4 } from "path";
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname2, join as join5 } from "path";
 import { existsSync } from "fs";
-import { dirname as dirname22, join as join5 } from "path";
+import { dirname as dirname22, join as join6 } from "path";
+import { basename as basename3 } from "path";
 import { readdirSync as readdirSync2, readFileSync as readFileSync4, statSync } from "fs";
-import { join as join6, relative as relative2 } from "path";
+import { join as join7, relative as relative2 } from "path";
 import { z as z3 } from "zod";
 var ConfigSchema = z.object({
   ignore: z.array(z.string()).optional(),
@@ -289,6 +292,15 @@ var RULE_TEMPLATES = {
     risk: "untrusted_admin_surface",
     provider: "convex"
   },
+  "ss/convex/public-function-no-auth": {
+    actor: "public_user",
+    lane: "server_action",
+    asset: databaseAsset,
+    permission: "execute",
+    condition: "sensitive_public_function_no_auth",
+    risk: "anonymous_write",
+    provider: "convex"
+  },
   "ss/auth/api-route-no-auth": {
     actor: "public_user",
     lane: "http_route",
@@ -343,6 +355,15 @@ var RULE_TEMPLATES = {
     risk: "deploy_secret_exposure",
     provider: "deploy"
   },
+  "ss/vercel/config-access-risk": {
+    actor: "deploy_platform",
+    lane: "deploy_config",
+    asset: routeAsset,
+    permission: "execute",
+    condition: "vercel_public_deploy_surface",
+    risk: "deploy_secret_exposure",
+    provider: "vercel"
+  },
   "ss/client/server-secret-env-in-client": {
     actor: "frontend_bundle",
     lane: "env_variable",
@@ -720,6 +741,55 @@ function runAbsenceRule(rule, files, cache, ctx) {
   }
   return findings;
 }
+var PUBLIC_FUNCTION_RE = /\bexport\s+const\s+(?<name>[A-Za-z_$][\w$]*)\s*=\s*(?<kind>query|mutation|action)\s*\(/g;
+var INTERNAL_FUNCTION_RE = /\binternal(?:Query|Mutation|Action)\s*\(/;
+var AUTH_MARKER_RE = /\b(?:ctx\.auth|getAuthUserId|getUserIdentity|requireAuth|requireInternalToken|getCaller|requireRole|requireAdmin)\b/;
+var PUBLIC_INTENT_RE = /\b(?:seamshield-public|publicIntent|publicMutation|publicAction|allowAnonymous|rateLimit|rateLimiter|RATE_LIMITED|waitlist_join|emailHash|hashKey|normalizeEmail|isValidEmail)\b/;
+var SENSITIVE_ACTION_RE = /\b(?:ctx\.db\.(?:insert|patch|replace|delete)|process\.env|admin|tenant|team|org|role|invite|token|secret|apiKey|webhook|billing|subscription|delete|recompute|backfill|sync|migrate)\b/i;
+function lineForOffset(content, offset) {
+  return content.slice(0, offset).split(/\r?\n/).length;
+}
+function statementWindow(content, start) {
+  const end = content.indexOf("\nexport const", start + 1);
+  const next = end === -1 ? content.length : end;
+  return content.slice(start, next);
+}
+function isConvexSource(file) {
+  const rel = file.rel.split("\\").join("/");
+  return rel.startsWith("convex/") && !rel.includes("/_generated/") && (rel.endsWith(".ts") || rel.endsWith(".js"));
+}
+function checkConvexPublicFunctions(rule, files, cache, ctx) {
+  const findings = [];
+  for (const file of files) {
+    if (!isConvexSource(file)) continue;
+    const content = cache.read(file.abs);
+    if (content === null) continue;
+    if (INTERNAL_FUNCTION_RE.test(content)) continue;
+    PUBLIC_FUNCTION_RE.lastIndex = 0;
+    for (const match of content.matchAll(PUBLIC_FUNCTION_RE)) {
+      const kind = match.groups?.kind;
+      const name = match.groups?.name ?? "function";
+      const offset = match.index ?? 0;
+      const window = statementWindow(content, offset);
+      if (AUTH_MARKER_RE.test(window) || PUBLIC_INTENT_RE.test(window)) continue;
+      if (kind === "query" && !SENSITIVE_ACTION_RE.test(window)) continue;
+      if (!SENSITIVE_ACTION_RE.test(window)) continue;
+      const line = lineForOffset(content, offset);
+      const lines = content.split(/\r?\n/);
+      if (isSuppressed(lines, line - 1, rule.id)) continue;
+      findings.push(
+        buildFinding(
+          rule,
+          file.rel,
+          line,
+          `${kind ?? "function"} ${name} has sensitive server capability and no recognized auth marker`,
+          ctx
+        )
+      );
+    }
+  }
+  return findings;
+}
 var ALLOWED = /* @__PURE__ */ new Set([".env.example", ".env.sample", ".env.template"]);
 var ENV_FILE_RE = /^\.env(\..+)?$/;
 function checkEnvFileCommitted(rule, ctx) {
@@ -820,10 +890,114 @@ function writeMarkdownFixPlan(result, options = {}) {
   writeFileSync(path, buildFixPlan(result, { agent: options.agent }).agent_markdown);
   return path;
 }
+var SEVERITIES = ["block", "high", "warn", "info"];
+function dateStamp2(now = /* @__PURE__ */ new Date()) {
+  return now.toISOString().slice(0, 10);
+}
+function countBy2(items, pick) {
+  const counts = {};
+  for (const item of items) counts[pick(item)] = (counts[pick(item)] ?? 0) + 1;
+  return counts;
+}
+function table(counts) {
+  const entries = Object.entries(counts).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  if (entries.length === 0) return ["_None._"];
+  return ["| Item | Count |", "| --- | ---: |", ...entries.map(([key, value]) => `| \`${key}\` | ${value} |`)];
+}
+function laneLine(lane) {
+  return [
+    `- \`${lane.severity}\` \`${lane.source.rule_id}\``,
+    `  ${lane.actor} -> ${lane.lane} -> ${lane.asset} -> ${lane.permission}`,
+    `  (${lane.condition}, ${lane.risk})`,
+    `  at \`${lane.source.file}:${lane.source.line}\``
+  ].join(" ");
+}
+function sectionFor(title, lanes, limit) {
+  if (lanes.length === 0) return [`## ${title}`, "", "_None._", ""];
+  const shown = lanes.slice(0, limit);
+  const remaining = lanes.length - shown.length;
+  return [
+    `## ${title}`,
+    "",
+    ...shown.map(laneLine),
+    ...remaining > 0 ? [`- ... ${remaining} more not shown in this summary.`] : [],
+    ""
+  ];
+}
+function renderInvestigationMarkdown(result, options = {}) {
+  const access = buildAccessMap(result);
+  const verdict = buildShipVerdict(result);
+  const lanes = access.lanes;
+  const limit = options.itemLimit ?? 80;
+  const bySeverity = countBy2(lanes, (lane) => lane.severity);
+  const byProvider = countBy2(lanes, (lane) => lane.provider);
+  const byRisk = countBy2(lanes, (lane) => lane.risk);
+  const critical = lanes.filter((lane) => lane.severity === "block" || lane.severity === "high");
+  const warnings = lanes.filter((lane) => lane.severity === "warn");
+  const info = lanes.filter((lane) => lane.severity === "info");
+  return [
+    "# SeamShield Investigation",
+    "",
+    `Date: ${dateStamp2(options.now)}`,
+    `Target: \`${result.target}\``,
+    `Verdict: **${verdict.verdict}**`,
+    `Policy bundle: \`${result.policyBundleDigest}\``,
+    "",
+    "## What This Means",
+    "",
+    verdict.verdict === "SAFE TO SHIP" ? "No block or high unsafe-to-ship access lanes were found by the controls that ran. Warnings still deserve triage." : "One or more block/high access lanes were found. Treat these as release blockers until fixed or explicitly triaged.",
+    "",
+    "SeamShield reports access-lane risk. It does not claim that the whole app has no vulnerabilities.",
+    "",
+    "## Summary",
+    "",
+    `- Files scanned: ${result.filesScanned}`,
+    `- Rules loaded: ${result.rulesLoaded}`,
+    `- Findings: ${result.findings.length}`,
+    `- Access lanes: ${lanes.length}`,
+    "",
+    "### By Severity",
+    "",
+    ...table(Object.fromEntries(SEVERITIES.map((severity) => [severity, bySeverity[severity] ?? 0]))),
+    "",
+    "### By Provider",
+    "",
+    ...table(byProvider),
+    "",
+    "### By Risk",
+    "",
+    ...table(byRisk),
+    "",
+    ...sectionFor("Critical Access Lanes", critical, limit),
+    ...sectionFor("Warnings To Triage", warnings, limit),
+    ...sectionFor("Informational Findings", info, Math.min(limit, 30)),
+    "## Suggested Next Steps",
+    "",
+    "- Run `seamshield access --format table` to inspect normalized lanes.",
+    "- Run `seamshield fix-plan --agent codex` to generate provider-aware remediation prompts.",
+    "- Use `seamshield triage --rule <rule-id>` only after validating a false positive or accepted risk.",
+    ""
+  ].join("\n");
+}
+function writeInvestigationMarkdown(result, options = {}) {
+  const dir = join3(result.target, ".seamshield", "investigations");
+  mkdirSync2(dir, { recursive: true });
+  const path = join3(dir, `${dateStamp2(options.now)}-access-lanes.md`);
+  writeFileSync2(path, renderInvestigationMarkdown(result, options));
+  return path;
+}
 var PatternSchema = z2.object({
   name: z2.string().min(1),
   regex: z2.string().min(1)
 });
+var BuiltinSchema = z2.enum([
+  "env-file-committed",
+  "no-lockfile",
+  "hallucinated-package",
+  "known-vuln",
+  "convex-public-function-no-auth",
+  "vercel-config"
+]);
 var RuleSchema = z2.object({
   id: z2.string().regex(/^ss\/[a-z-]+\/[a-z0-9-]+$/),
   severity: z2.enum(["block", "high", "warn", "info"]),
@@ -832,7 +1006,7 @@ var RuleSchema = z2.object({
   framework_ref: z2.string().min(1),
   check: z2.object({
     type: z2.enum(["regex", "absence", "builtin"]),
-    builtin: z2.string().optional(),
+    builtin: BuiltinSchema.optional(),
     include: z2.object({
       extensions: z2.array(z2.string()).optional(),
       basenames: z2.array(z2.string()).optional(),
@@ -862,7 +1036,7 @@ function loadRules(rulesDir2) {
   const hash = createHash("sha256");
   const contents = /* @__PURE__ */ new Map();
   for (const name of yamlFiles) {
-    const text = readFileSync2(join3(rulesDir2, name), "utf8");
+    const text = readFileSync2(join4(rulesDir2, name), "utf8");
     contents.set(name, text);
     hash.update(name);
     hash.update("\n");
@@ -1047,7 +1221,7 @@ function collectDependencies(ctx, files) {
 }
 function cachePath(ctx, kind, key) {
   const safe = encodeURIComponent(key).replace(/[!'()*]/g, "_");
-  return join4(ctx.root, ".seamshield", "cache", kind, `${safe}.json`);
+  return join5(ctx.root, ".seamshield", "cache", kind, `${safe}.json`);
 }
 function readCache(ctx, kind, key) {
   try {
@@ -1061,8 +1235,8 @@ function readCache(ctx, kind, key) {
 }
 function writeCache(ctx, kind, key, value) {
   const path = cachePath(ctx, kind, key);
-  mkdirSync2(dirname2(path), { recursive: true });
-  writeFileSync2(path, JSON.stringify({ ok: true, value, time: Date.now() }));
+  mkdirSync3(dirname2(path), { recursive: true });
+  writeFileSync3(path, JSON.stringify({ ok: true, value, time: Date.now() }));
 }
 async function fetchJson(url, init, timeoutMs, fetchImpl) {
   const controller = new AbortController();
@@ -1172,16 +1346,119 @@ async function checkKnownVulnerabilities(rule, ctx, files, options = {}) {
 }
 var LOCKFILES = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb", "bun.lock"];
 function checkNoLockfile(rule, ctx) {
-  if (!existsSync(join5(ctx.root, "package.json"))) return [];
+  if (!existsSync(join6(ctx.root, "package.json"))) return [];
   let dir = ctx.root;
   for (let depth = 0; depth < 8; depth++) {
-    if (LOCKFILES.some((name) => existsSync(join5(dir, name)))) return [];
+    if (LOCKFILES.some((name) => existsSync(join6(dir, name)))) return [];
     const parent = dirname22(dir);
     if (parent === dir) break;
     dir = parent;
   }
   return [buildFinding(rule, "package.json", 1, "no lockfile found next to package.json", ctx)];
 }
+var PUBLIC_SECRET_ENV_RE = /^(?:NEXT_PUBLIC_|VITE_|PUBLIC_).*(?:SECRET|PRIVATE|PASSWORD|SERVICE_ROLE|API_KEY|TOKEN)/i;
+var ADMIN_ROUTE_RE = /\/(?:api\/)?(?:admin|internal|debug|ops|backoffice)(?:\/|$)/i;
+function walkJson(value, visit, path = []) {
+  visit(path, value);
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => walkJson(item, visit, [...path, String(index)]));
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const [key, item] of Object.entries(value)) walkJson(item, visit, [...path, key]);
+  }
+}
+function valueAtPath(root, path) {
+  let current = root;
+  for (const segment of path) {
+    if (Array.isArray(current)) {
+      current = current[Number(segment)];
+      continue;
+    }
+    if (!current || typeof current !== "object") return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+function hasVercelAuthSignal(root) {
+  let found = false;
+  walkJson(root, (path, value) => {
+    if (found || typeof value !== "string") return;
+    const key = path[path.length - 1] ?? "";
+    if (/authorization|x-vercel-protection-bypass|middleware|auth|token/i.test(`${key}:${value}`)) {
+      found = true;
+    }
+  });
+  return found;
+}
+function lineForNeedle(content, needle) {
+  const index = content.indexOf(needle);
+  if (index === -1) return 1;
+  return content.slice(0, index).split(/\r?\n/).length;
+}
+function addFinding(findings, rule, file, line, evidence, ctx) {
+  findings.push(buildFinding(rule, file, line, evidence.slice(0, 120), ctx));
+}
+function checkVercelConfig(rule, files, cache, ctx) {
+  const findings = [];
+  for (const file of files) {
+    if (basename3(file.rel) !== "vercel.json") continue;
+    const content = cache.read(file.abs);
+    if (content === null) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(content);
+    } catch {
+      continue;
+    }
+    const hasAuthSignal = hasVercelAuthSignal(parsed);
+    walkJson(parsed, (path, value) => {
+      const key = path[path.length - 1] ?? "";
+      if (typeof value !== "string") return;
+      if (PUBLIC_SECRET_ENV_RE.test(key)) {
+        addFinding(findings, rule, file.rel, lineForNeedle(content, key), `public env ${key}`, ctx);
+      }
+      const joinedPath = path.join(".");
+      if (/^(routes|rewrites|redirects)\.\d+\.(source|src|destination|dest)$/.test(joinedPath) && ADMIN_ROUTE_RE.test(value) && !hasAuthSignal) {
+        addFinding(
+          findings,
+          rule,
+          file.rel,
+          lineForNeedle(content, value),
+          `public ${joinedPath} exposes ${value}`,
+          ctx
+        );
+      }
+      if (/^crons\.\d+\.path$/.test(joinedPath) && ADMIN_ROUTE_RE.test(value) && !hasAuthSignal) {
+        addFinding(
+          findings,
+          rule,
+          file.rel,
+          lineForNeedle(content, value),
+          `cron path targets privileged route ${value}`,
+          ctx
+        );
+      }
+    });
+    const headers = valueAtPath(parsed, ["headers"]);
+    if (Array.isArray(headers)) {
+      for (const header of headers) {
+        const stringified = JSON.stringify(header);
+        if (/access-control-allow-origin/i.test(stringified) && /"\*"/.test(stringified) && /access-control-allow-credentials/i.test(stringified) && /true/i.test(stringified)) {
+          addFinding(
+            findings,
+            rule,
+            file.rel,
+            lineForNeedle(content, "Access-Control-Allow-Origin"),
+            "wildcard CORS origin with credentials in vercel.json",
+            ctx
+          );
+        }
+      }
+    }
+  }
+  return findings;
+}
 var SKIP_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
   ".git",
@@ -1198,8 +1475,53 @@ var SKIP_DIRS = /* @__PURE__ */ new Set([
   ".pnpm-store"
 ]);
 var MAX_FILE_BYTES = 1e6;
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function globToRegex(pattern) {
+  let source = "";
+  for (const char of pattern) {
+    source += char === "*" ? "[^/]*" : escapeRegex(char);
+  }
+  return new RegExp(`^${source}$`);
+}
+function loadGitignore(root) {
+  let text;
+  try {
+    text = readFileSync4(join7(root, ".gitignore"), "utf8");
+  } catch {
+    return [];
+  }
+  return text.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#")).map((line) => {
+    const negated = line.startsWith("!");
+    return { pattern: (negated ? line.slice(1) : line).replace(/^\/+/, ""), negated };
+  }).filter((rule) => rule.pattern.length > 0);
+}
+function globMatches(value, pattern) {
+  const normalized = value.split("\\").join("/");
+  const clean = pattern.replace(/\/$/, "");
+  if (clean.includes("*")) {
+    const re = globToRegex(clean);
+    if (re.test(normalized)) return true;
+    const base = normalized.split("/").pop() ?? normalized;
+    return !clean.includes("/") && re.test(base);
+  }
+  if (clean.includes("/")) return normalized === clean || normalized.startsWith(`${clean}/`);
+  const segments = normalized.split("/");
+  return segments.includes(clean);
+}
+function isGitIgnored(rel, rules) {
+  let ignored = false;
+  const normalized = rel.split("\\").join("/");
+  for (const rule of rules) {
+    if (!globMatches(normalized, rule.pattern)) continue;
+    ignored = !rule.negated;
+  }
+  return ignored;
+}
 function walk(root) {
   const files = [];
+  const gitignore = loadGitignore(root);
   const visit = (dir) => {
     let entries;
     try {
@@ -1209,12 +1531,13 @@ function walk(root) {
     }
     for (const entry of entries) {
       if (entry.isSymbolicLink()) continue;
-      const abs = join6(dir, entry.name);
+      const abs = join7(dir, entry.name);
       if (entry.isDirectory()) {
         const rel = relative2(root, abs).split("\\").join("/");
         if (SKIP_DIRS.has(entry.name)) continue;
         if (entry.name === ".worktrees") continue;
         if (rel === ".claude/worktrees" || rel.endsWith("/.claude/worktrees")) continue;
+        if (isGitIgnored(rel, gitignore)) continue;
         visit(abs);
       } else if (entry.isFile()) {
         try {
@@ -1222,7 +1545,9 @@ function walk(root) {
         } catch {
           continue;
         }
-        files.push({ abs, rel: relative2(root, abs) });
+        const rel = relative2(root, abs).split("\\").join("/");
+        if (isGitIgnored(rel, gitignore)) continue;
+        files.push({ abs, rel });
       }
     }
   };
@@ -1266,6 +1591,10 @@ function scan(target, options = {}) {
       findings.push(...checkEnvFileCommitted(rule, ctx));
     } else if (rule.check.builtin === "no-lockfile") {
       findings.push(...checkNoLockfile(rule, ctx));
+    } else if (rule.check.builtin === "convex-public-function-no-auth") {
+      findings.push(...checkConvexPublicFunctions(rule, files, cache, ctx));
+    } else if (rule.check.builtin === "vercel-config") {
+      findings.push(...checkVercelConfig(rule, files, cache, ctx));
     } else if (rule.check.builtin === "hallucinated-package" || rule.check.builtin === "known-vuln") {
       continue;
     } else {
@@ -1413,6 +1742,7 @@ var FORMATS = ["table", "json", "sarif"];
 var ACCESS_FORMATS = ["table", "json"];
 var FAIL_ON = ["block", "high", "warn", "never"];
 var FIX_AGENTS = ["claude", "cursor", "codex", "generic"];
+var CONTEXT_AGENTS = ["claude", "cursor", "codex"];
 function assertChoice(value, allowed, label) {
   if (value && !allowed.includes(value)) {
     console.error(`seamshield: unknown --${label} "${value}" (expected: ${allowed.join(", ")})`);
@@ -1437,6 +1767,11 @@ function render(format, result) {
   if (format === "sarif") return renderSarif(result);
   return renderTable(result);
 }
+function maybeWriteInvestigation(result, enabled) {
+  if (enabled === false) return;
+  const out = writeInvestigationMarkdown(result);
+  console.error(`Investigation written: ${out}`);
+}
 async function runScan(path, opts) {
   if (!assertOptions(opts)) return;
   if (!existsSync2(path)) {
@@ -1449,6 +1784,7 @@ async function runScan(path, opts) {
       failOn: opts.failOn,
       network: opts.offline ? "off" : "on"
     });
+    maybeWriteInvestigation(result, opts.investigation);
     console.log(render(opts.format, result));
     process.exitCode = result.exitCode;
   } catch (error) {
@@ -1470,42 +1806,45 @@ async function readScanForCommand(path, offline = true) {
     return null;
   }
 }
+function writeSection(path, marker, body) {
+  mkdirSync4(dirname3(path), { recursive: true });
+  const existing = existsSync2(path) ? readFileSync6(path, "utf8") : "";
+  const next = existing.includes(marker) ? existing.replace(new RegExp(`${marker}[\\s\\S]*?(?=\\n# |\\n?$)`), body.trimEnd()) : `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${body}`;
+  writeFileSync4(path, next.endsWith("\n") ? next : `${next}
+`);
+  return path;
+}
 function writeAgentContext(target, kind) {
   const body = [
     "# SEAMSHIELD",
     "",
-    "- Run `npx seamshield scan --offline` before committing AI-generated changes.",
+    "- Run `npx seamshield ship .` before deploys and `npx seamshield scan --offline` before committing AI-generated changes.",
+    "- Review `.seamshield/investigations/` after scans; it explains findings and open access lanes in Markdown.",
     "- Never hardcode provider keys, service-role keys, private keys, or dotenv contents.",
     "- Do not expose server secrets through `NEXT_PUBLIC_*` or client components.",
     "- Do not rely on client-only auth for private data; enforce auth server-side.",
-    "- Keep Supabase RLS enabled and Firebase rules closed by default.",
-    "- If SeamShield reports findings, apply the generated `npx seamshield fix-plan` prompts.",
+    "- Keep Supabase RLS enabled, Firebase rules closed by default, and Convex privileged mutations authenticated or internal.",
+    `- If SeamShield reports findings, inspect \`npx seamshield access .\` and apply \`npx seamshield fix-plan . --agent ${kind === "codex" ? "codex" : kind}\`.`,
     ""
   ].join("\n");
   if (kind === "cursor") {
-    const out2 = join7(target, ".cursor", "rules", "seamshield.mdc");
-    mkdirSync3(dirname3(out2), { recursive: true });
-    writeFileSync3(out2, body);
-    return out2;
+    const out = join8(target, ".cursor", "rules", "seamshield.mdc");
+    mkdirSync4(dirname3(out), { recursive: true });
+    writeFileSync4(out, body);
+    return out;
   }
-  const out = join7(target, "CLAUDE.md");
-  const existing = existsSync2(out) ? readFileSync6(out, "utf8") : "";
-  const marker = "# SEAMSHIELD";
-  const next = existing.includes(marker) ? existing.replace(/# SEAMSHIELD[\s\S]*?(?=\n# |\n?$)/, body.trimEnd()) : `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${body}`;
-  writeFileSync3(out, next.endsWith("\n") ? next : `${next}
-`);
-  return out;
+  return writeSection(join8(target, kind === "codex" ? "AGENTS.md" : "CLAUDE.md"), "# SEAMSHIELD", body);
 }
 function readTriageConfig(target) {
-  const path = join7(target, ".seamshield", "config.yaml");
+  const path = join8(target, ".seamshield", "config.yaml");
   if (!existsSync2(path)) return {};
   const parsed = parse3(readFileSync6(path, "utf8"));
   return parsed && typeof parsed === "object" ? parsed : {};
 }
 function writeTriageConfig(target, config) {
-  const out = join7(target, ".seamshield", "config.yaml");
-  mkdirSync3(dirname3(out), { recursive: true });
-  writeFileSync3(out, stringify(config));
+  const out = join8(target, ".seamshield", "config.yaml");
+  mkdirSync4(dirname3(out), { recursive: true });
+  writeFileSync4(out, stringify(config));
   return out;
 }
 async function writeTriageSuppressions(path, opts) {
@@ -1541,8 +1880,8 @@ function currentBin() {
   return fileURLToPath2(import.meta.url);
 }
 function installGuard(target) {
-  const settingsPath = join7(target, ".claude", "settings.json");
-  mkdirSync3(dirname3(settingsPath), { recursive: true });
+  const settingsPath = join8(target, ".claude", "settings.json");
+  mkdirSync4(dirname3(settingsPath), { recursive: true });
   const settings = existsSync2(settingsPath) ? JSON.parse(readFileSync6(settingsPath, "utf8")) : {};
   const hooks = settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {};
   const command = `${process.execPath} ${JSON.stringify(currentBin())} guard check`;
@@ -1553,7 +1892,7 @@ function installGuard(target) {
     }
   ];
   settings.hooks = hooks;
-  writeFileSync3(settingsPath, `${JSON.stringify(settings, null, 2)}
+  writeFileSync4(settingsPath, `${JSON.stringify(settings, null, 2)}
 `);
   return settingsPath;
 }
@@ -1614,10 +1953,10 @@ function guardCheck() {
       console.log(JSON.stringify(hookAllow()));
       return;
     }
-    const tempRoot = mkdtempSync(join7(tmpdir(), "seamshield-guard-"));
-    const abs = join7(tempRoot, proposed.rel.replace(/^\/+/, ""));
-    mkdirSync3(dirname3(abs), { recursive: true });
-    writeFileSync3(abs, proposed.content);
+    const tempRoot = mkdtempSync(join8(tmpdir(), "seamshield-guard-"));
+    const abs = join8(tempRoot, proposed.rel.replace(/^\/+/, ""));
+    mkdirSync4(dirname3(abs), { recursive: true });
+    writeFileSync4(abs, proposed.content);
     const result = scan(tempRoot, { network: "off" });
     rmSync(tempRoot, { recursive: true, force: true });
     const block = result.findings.find((f) => f.finding.severity === "block");
@@ -1631,10 +1970,10 @@ function guardCheck() {
     }
     console.log(JSON.stringify(hookAllow()));
   } catch (error) {
-    const logPath = join7(process.cwd(), ".seamshield", "guard.log");
+    const logPath = join8(process.cwd(), ".seamshield", "guard.log");
     try {
-      mkdirSync3(dirname3(logPath), { recursive: true });
-      writeFileSync3(logPath, `${(/* @__PURE__ */ new Date()).toISOString()} ${String(error)}
+      mkdirSync4(dirname3(logPath), { recursive: true });
+      writeFileSync4(logPath, `${(/* @__PURE__ */ new Date()).toISOString()} ${String(error)}
 `, { flag: "a" });
     } catch {
     }
@@ -1643,16 +1982,23 @@ function guardCheck() {
 }
 var program = new Command();
 program.name("seamshield").description("Security scanner for AI-generated apps: finds the flaws vibecoded projects predictably ship.").version(pkg.version);
-program.command("scan").description("Scan a project directory and report findings").argument("[path]", "directory to scan", ".").option("--format <format>", "output format: table | json | sarif", "table").option("--fail-on <severity>", "exit 1 at or above: block | high | warn | never", "block").option("--offline", "skip npm registry and OSV network checks").action((path, opts) => {
+program.command("scan").description("Scan a project directory and report findings").argument("[path]", "directory to scan", ".").option("--format <format>", "output format: table | json | sarif", "table").option("--fail-on <severity>", "exit 1 at or above: block | high | warn | never", "block").option("--offline", "skip npm registry and OSV network checks").option("--no-investigation", "do not write .seamshield/investigations/*.md").action((path, opts) => {
   return runScan(path, opts);
 });
 program.command("ship").description("Give a deploy verdict from dangerous access lanes").argument("[path]", "directory to scan", ".").option("--online", "include network-backed dependency intelligence").action(async (path, opts) => {
   const result = await readScanForCommand(path, !opts.online);
   if (!result) return;
+  maybeWriteInvestigation(result, true);
   const verdict = buildShipVerdict(result);
   console.log(renderShipTable(verdict));
   process.exitCode = verdict.exitCode;
 });
+program.command("investigate").description("Write a Markdown investigation for current access-lane findings").argument("[path]", "directory to scan", ".").option("--online", "include network-backed dependency intelligence").action(async (path, opts) => {
+  const result = await readScanForCommand(path, !opts.online);
+  if (!result) return;
+  console.log(writeInvestigationMarkdown(result));
+  process.exitCode = 0;
+});
 program.command("access").description("Show the normalized Actor -> Lane -> Asset -> Permission -> Condition -> Risk access map").argument("[path]", "directory to scan", ".").option("--format <format>", "output format: table | json", "table").option("--online", "include network-backed dependency intelligence").action(async (path, opts) => {
   if (!assertChoice(opts.format, ACCESS_FORMATS, "format")) return;
   const result = await readScanForCommand(path, !opts.online);
@@ -1669,9 +2015,9 @@ program.command("fix-plan").description("Write agent-ready fix prompts for dange
     return;
   }
   const result = await scanAsync(path, { network: opts.offline ? "off" : "on" });
-  const out = join7(resolve2(path), ".seamshield", "fix-plan.json");
-  mkdirSync3(dirname3(out), { recursive: true });
-  writeFileSync3(out, `${JSON.stringify(buildFixPlan(result, { agent: opts.agent }), null, 2)}
+  const out = join8(resolve2(path), ".seamshield", "fix-plan.json");
+  mkdirSync4(dirname3(out), { recursive: true });
+  writeFileSync4(out, `${JSON.stringify(buildFixPlan(result, { agent: opts.agent }), null, 2)}
 `);
   const markdownOut = writeMarkdownFixPlan(result, { agent: opts.agent });
   console.log(out);
@@ -1688,9 +2034,19 @@ program.command("learn").description("Update local controls from vulnerability i
 program.command("triage").description("Persist current false-positive decisions into .seamshield/config.yaml").argument("[path]", "directory to scan", ".").option("--rule <rule-id>", "only suppress current findings from one rule").option("--reason <text>", "suppression reason", "triaged false positive").option("--include-block", "also suppress block findings", false).option("--online", "include network-backed dependency intelligence").action(
   (path, opts) => writeTriageSuppressions(path, opts)
 );
-program.command("agent-context").description("Write SeamShield agent instructions into CLAUDE.md or Cursor rules").argument("[path]", "project directory", ".").option("--claude", "write CLAUDE.md", false).option("--cursor", "write .cursor/rules/seamshield.mdc", false).action((path, opts) => {
+program.command("agent-context").description("Write SeamShield agent instructions into AGENTS.md, CLAUDE.md, or Cursor rules").argument("[path]", "project directory", ".").option("--claude", "write CLAUDE.md", false).option("--cursor", "write .cursor/rules/seamshield.mdc", false).option("--codex", "write AGENTS.md", false).action((path, opts) => {
+  const selected = [
+    opts.claude ? "claude" : null,
+    opts.cursor ? "cursor" : null,
+    opts.codex ? "codex" : null
+  ].filter(Boolean);
+  if (selected.length > 1) {
+    console.error(`seamshield: choose one agent context (${CONTEXT_AGENTS.join(", ")})`);
+    process.exitCode = 2;
+    return;
+  }
   const target = resolve2(path);
-  const kind = opts.cursor ? "cursor" : "claude";
+  const kind = selected[0] ?? "codex";
   console.log(writeAgentContext(target, kind));
 });
 var guard = program.command("guard").description("Claude Code guard utilities");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seamshield",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Security scanner for AI-generated apps: finds the flaws vibecoded projects predictably ship",
   "type": "module",
   "license": "MIT",
@@ -57,7 +57,7 @@
     "@seamshield/rules": "0.1.0"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --clean && tsc -p tsconfig.build.json && rm -rf rules schemas && cp -R ../rules/rules ../rules/schemas .",
+    "build": "tsup src/index.ts --format esm --clean && tsc -p tsconfig.build.json && rm -rf rules schemas && ditto ../rules/rules rules && ditto ../rules/schemas schemas",
     "test": "vitest run"
   }
 }

package/rules/ss-convex-mutation-no-auth.yaml

@@ -16,7 +16,7 @@ check:
   file_contains: "(?<![A-Za-z])mutation\\s*\\("
   patterns:
     - name: convex-auth-markers
-      regex: "ctx\\.auth|getAuthUserId|getUserIdentity|requireAuth|requireInternalToken|getCaller|requireRole|requireAdmin|internalMutation|rateLimit|rateLimiter|RATE_LIMITED|emailHash|hashKey|normalizeEmail|isValidEmail|waitlist_join"
+      regex: "ctx\\.auth|getAuthUserId|getUserIdentity|requireAuth|requireInternalToken|getCaller|requireRole|requireAdmin|internalMutation|seamshield-public|publicIntent|publicMutation|allowAnonymous|rateLimit|rateLimiter|RATE_LIMITED|emailHash|hashKey|normalizeEmail|isValidEmail|waitlist_join"
 fix:
   summary: Verify the caller with ctx.auth at the top of the mutation, or make it internal.
   agent_prompt: >

package/rules/ss-convex-public-function-no-auth.yaml

@@ -0,0 +1,20 @@
+id: ss/convex/public-function-no-auth
+severity: warn
+title: Public Convex function with sensitive capability and no auth check
+description: >
+  A public Convex query, mutation, or action touches sensitive server capability
+  such as database writes, privileged tenant/team paths, secrets, or admin-like
+  operations without a recognized auth or internal-only guard.
+framework_ref: OPEN_CORE.md#oss-scanner-boundary
+check:
+  type: builtin
+  builtin: convex-public-function-no-auth
+fix:
+  summary: Add a server-side auth/role guard, mark the function internal, or explicitly document safe public intent.
+  agent_prompt: >
+    Review this Convex function as a public entrypoint. If it changes data,
+    accesses tenant/team/admin state, or reads privileged runtime capability,
+    add ctx.auth/getAuthUserId plus the required role or tenant check near the
+    top. If it is server-only, convert it to internalQuery/internalMutation/
+    internalAction. If it is intentionally public and low risk, add an explicit
+    public-intent marker and rate limit instead of weakening auth checks.

package/rules/ss-secrets-private-key-file.yaml

@@ -8,8 +8,11 @@ description: >
 framework_ref: AI_AGENT_DROP_IN.md#default-security-stance
 check:
   type: regex
+  include:
+    extensions: [".pem", ".key", ".crt", ".cer", ".p12", ".pfx", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json", ".yaml", ".yml"]
+    basenames: ["id_rsa", "id_dsa", "id_ecdsa", "id_ed25519", "*.pem", "*.key"]
   exclude:
-    basenames: ["*.pub"]
+    basenames: ["*.pub", ".env", ".env.*", "*.env", "*.env.*"]
   patterns:
     - name: pem-private-key
       regex: "-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY-----"

package/rules/ss-vercel-config-access-risk.yaml

@@ -0,0 +1,19 @@
+id: ss/vercel/config-access-risk
+severity: high
+title: Vercel config opens a risky access lane
+description: >
+  vercel.json exposes a public/client secret, wildcard credentialed CORS, or a
+  privileged route through rewrites, routes, redirects, or cron paths without an
+  obvious auth/protection signal.
+framework_ref: OPEN_CORE.md#oss-scanner-boundary
+check:
+  type: builtin
+  builtin: vercel-config
+fix:
+  summary: Move secrets to server-only env, restrict public headers, and protect privileged Vercel routes.
+  agent_prompt: >
+    Inspect vercel.json and close the risky access lane. Do not place secrets in
+    NEXT_PUBLIC_, VITE_, or PUBLIC_ variables. Avoid wildcard credentialed CORS.
+    For admin/internal/debug/ops routes, require middleware, authorization
+    headers, or Vercel protection before the route can be reached from the
+    public internet.