seamshield 0.1.3 → 0.2.0

package/README.md

@@ -1,20 +1,21 @@
 # SeamShield
 
-Local security scanner for AI-built JavaScript and TypeScript apps.
+Local access-lane security scanner for AI-built JavaScript and TypeScript apps.
 
-SeamShield finds common flaws that AI-generated apps often ship: committed secrets, client-exposed server keys, client-only auth, open platform rules, unsafe agent config, and dependency supply-chain risks.
+SeamShield maps who or what can reach sensitive assets before you ship:
+`Actor -> Lane -> Asset -> Permission -> Condition -> Risk`.
 
 ## Install
 
 ```bash
-npx seamshield scan .
+npx seamshield ship .
 ```
 
 Or install globally:
 
 ```bash
 npm install -g seamshield
-seamshield scan .
+seamshield ship .
 ```
 
 Requires Node.js 20 or newer.
@@ -22,14 +23,38 @@ Requires Node.js 20 or newer.
 ## Commands
 
 ```bash
-seamshield scan .
-seamshield fix-plan .
+seamshield ship .
+seamshield access . --format table
+seamshield access . --format json
+seamshield scan . --offline
+seamshield fix-plan . --agent codex
+seamshield triage . --rule ss/auth/client-only-guard
 seamshield agent-context . --claude
 seamshield agent-context . --cursor
 seamshield guard install .
-seamshield guard check
+seamshield learn
+```
+
+## Ship Verdict
+
+```bash
+seamshield ship .
+```
+
+Runs locally and prints `SAFE TO SHIP` only when there are no block or high
+access-lane risks. Use this before deploys.
+
+## Access Map
+
+```bash
+seamshield access . --format json
 ```
 
+Outputs normalized access lanes while preserving provider-specific evidence.
+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.
+
 ## Scan
 
 ```bash
@@ -42,40 +67,49 @@ seamshield scan . --offline
 
 Exit codes:
 
-- `0` - no findings at or above the selected `--fail-on` threshold.
-- `1` - findings at or above the threshold.
+- `0` - no findings at or above the selected threshold.
+- `1` - findings at or above the selected threshold.
 - `2` - CLI usage or scanner failure.
 
 `--offline` disables npm registry and OSV checks. Static rules still run.
 
-## Fix Plans
+## Triage
 
 ```bash
-seamshield fix-plan .
+seamshield triage . --rule ss/auth/client-only-guard
 ```
 
-Writes `.seamshield/fix-plan.json` with redacted findings and agent-ready remediation prompts.
+Persists current false-positive decisions into `.seamshield/config.yaml` as
+exact rule/file/line suppressions. Block findings are not triaged unless
+`--include-block` is provided.
 
-## Agent Context
+## Fix Plans
 
 ```bash
-seamshield agent-context . --claude
-seamshield agent-context . --cursor
+seamshield fix-plan . --agent claude
+seamshield fix-plan . --agent cursor
+seamshield fix-plan . --agent codex
+seamshield fix-plan . --agent generic
 ```
 
-Claude writes or updates `CLAUDE.md`. Cursor writes `.cursor/rules/seamshield.mdc`.
+Writes `.seamshield/fix-plan.json` and a Markdown plan under
+`.seamshield/fix-plans/` with redacted findings and provider-aware prompts.
 
-## Claude Code Guard
+## Agent Guard
 
 ```bash
+seamshield agent-context . --claude
+seamshield agent-context . --cursor
 seamshield guard install .
 ```
 
-Installs a Claude Code `PreToolUse` hook for `Write`, `Edit`, `MultiEdit`, and `Bash`.
-
-The guard denies block-severity edits such as hardcoded provider keys, service-role keys, private keys, committed dotenv files, open Firebase rules, or RLS disablement. Bash checks deny obvious dangerous commands such as `git add .env*`, `curl ... | sh`, and installs of npm packages that do not resolve.
+`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.
 
-Guard behavior is fail-open: if the hook errors, it allows the tool call and appends diagnostics to `.seamshield/guard.log`.
+Guard behavior is fail-open: if the hook errors, it allows the tool call and
+appends diagnostics to `.seamshield/guard.log`.
 
 ## Configuration
 
@@ -84,6 +118,11 @@ Create `.seamshield/config.yaml`:
 ```yaml
 ignore:
   - vendored/**
+suppress:
+  - rule: ss/auth/client-only-guard
+    file: app/dashboard/page.tsx
+    line: 42
+    reason: server-side route enforces auth
 rules:
   disable:
     - ss/auth/client-only-guard
@@ -100,19 +139,9 @@ const fixtureKey = "sk_live_test_fixture_only";
 
 SeamShield runs locally. Static scanning does not transmit source code.
 
-Network dependency checks send package names and versions to the npm registry and OSV. Use `--offline` to disable those checks.
-
-Secret evidence is redacted before findings, JSON, SARIF, and fix plans are emitted.
-
-## Public Rule Coverage
-
-- Secrets and client exposure
-- Next.js auth footguns
-- Supabase, Convex, and Firebase platform mistakes
-- Dependency lockfile, pinning, hallucinated-package, and OSV vulnerability checks
-- Agent config secrets and overbroad permissions
-
-## Links
+Network dependency checks send package names and versions to the npm registry
+and OSV. Use `--offline` or avoid `--online` on `ship` and `access` to keep the
+run fully local.
 
-- Repository: https://github.com/KaraboGerald/SeamShield
-- Issues: https://github.com/KaraboGerald/SeamShield/issues
+Secret evidence is redacted before findings, JSON, SARIF, and fix plans are
+emitted.

package/dist/index.js

@@ -99,14 +99,17 @@ var require_picocolors = __commonJS({
 });
 
 // src/index.ts
-import { spawnSync as spawnSync3 } from "child_process";
-import { existsSync as existsSync2, mkdirSync, mkdtempSync, readFileSync as readFileSync6, rmSync, writeFileSync } from "fs";
+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 { tmpdir } from "os";
 import { dirname as dirname3, join as join7, resolve as resolve2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command } from "commander";
+import { parse as parse3, stringify } from "yaml";
 
 // ../core/dist/index.js
+var import_picocolors = __toESM(require_picocolors(), 1);
+var import_picocolors2 = __toESM(require_picocolors(), 1);
 import { readFileSync } from "fs";
 import { join as join2 } from "path";
 import { parse } from "yaml";
@@ -115,7 +118,8 @@ import { randomUUID } from "crypto";
 import { basename, extname } from "path";
 import { spawnSync } from "child_process";
 import { basename as basename2 } from "path";
-var import_picocolors = __toESM(require_picocolors(), 1);
+import { mkdirSync, writeFileSync } from "fs";
+import { join as join22 } from "path";
 import { createHash } from "crypto";
 import { readFileSync as readFileSync2, readdirSync } from "fs";
 import { join as join3 } from "path";
@@ -141,14 +145,21 @@ import { dirname as dirname2, join as join4 } from "path";
 import { existsSync } from "fs";
 import { dirname as dirname22, join as join5 } from "path";
 import { readdirSync as readdirSync2, readFileSync as readFileSync4, statSync } from "fs";
-import { spawnSync as spawnSync2 } from "child_process";
 import { join as join6, relative as relative2 } from "path";
 import { z as z3 } from "zod";
 var ConfigSchema = z.object({
   ignore: z.array(z.string()).optional(),
+  suppress: z.array(
+    z.object({
+      rule: z.string().min(1),
+      file: z.string().min(1),
+      line: z.number().int().positive().optional(),
+      reason: z.string().optional()
+    })
+  ).optional(),
   rules: z.object({ disable: z.array(z.string()).optional() }).optional()
 });
-var EMPTY = { ignorePrefixes: [], disabledRules: /* @__PURE__ */ new Set() };
+var EMPTY = { ignorePrefixes: [], disabledRules: /* @__PURE__ */ new Set(), suppressions: [] };
 function loadConfig(root) {
   let text;
   try {
@@ -161,15 +172,450 @@ function loadConfig(root) {
     ignorePrefixes: (parsed.ignore ?? []).map(
       (p) => p.replace(/\/\*{1,2}$/, "").replace(/\/$/, "")
     ),
-    disabledRules: new Set(parsed.rules?.disable ?? [])
+    disabledRules: new Set(parsed.rules?.disable ?? []),
+    suppressions: parsed.suppress ?? []
   };
 }
 function isIgnored(rel, prefixes) {
   return prefixes.some((p) => rel === p || rel.startsWith(`${p}/`));
 }
+function isSuppressedByConfig(ruleId, rel, line, suppressions) {
+  return suppressions.some(
+    (s) => s.rule === ruleId && s.file === rel && (s.line === void 0 || s.line === line)
+  );
+}
+var SEVERITY_RANK = {
+  block: 0,
+  high: 1,
+  warn: 2,
+  info: 3
+};
+var ROUTE_ASSET_RE = /^(?:app|pages)\/(.+?)(?:\/route)?\.[tj]sx?$/;
+function envAsset(finding) {
+  const evidence = finding.spans[0]?.evidence ?? "";
+  const upper = evidence.match(/[A-Z][A-Z0-9_]{3,}/)?.[0];
+  if (upper) return `env:${upper}`;
+  if (finding.finding.rule_id.includes("supabase")) return "env:SUPABASE_SERVICE_ROLE_KEY";
+  if (finding.finding.rule_id.includes("next-public")) return "env:NEXT_PUBLIC_*SECRET*";
+  return "env:server_secret";
+}
+function routeAsset(finding) {
+  const normalized = finding.finding.file.split("\\").join("/");
+  const route = ROUTE_ASSET_RE.exec(normalized)?.[1];
+  if (route) return `/${route.replace(/\/page$|\/route$/, "")}`;
+  return normalized;
+}
+function packageAsset(finding) {
+  const evidence = finding.spans[0]?.evidence ?? "";
+  const quoted = evidence.match(/"([^"]+)"/)?.[1];
+  return quoted && quoted.trim().length > 1 ? `package:${quoted}` : "package.json";
+}
+function databaseAsset(finding) {
+  if (finding.finding.file.includes("firestore")) return "firestore.rules";
+  if (finding.finding.file.includes("convex/")) return `convex:${routeAsset(finding)}`;
+  if (finding.finding.file.includes("supabase/")) return "supabase:database";
+  return finding.finding.file;
+}
+var RULE_TEMPLATES = {
+  "ss/client/supabase-service-role-in-client": {
+    actor: "frontend_bundle",
+    lane: "env_variable",
+    asset: envAsset,
+    permission: "read",
+    condition: "client_exposed",
+    risk: "client_to_server_secret",
+    provider: "supabase"
+  },
+  "ss/secrets/supabase-service-role-key": {
+    actor: "server_runtime",
+    lane: "env_variable",
+    asset: envAsset,
+    permission: "read",
+    condition: "hardcoded_or_committed",
+    risk: "server_secret_exposure",
+    provider: "supabase"
+  },
+  "ss/supabase/rls-disabled": {
+    actor: "public_user",
+    lane: "database",
+    asset: databaseAsset,
+    permission: "read",
+    condition: "rls_disabled",
+    risk: "public_database_access",
+    provider: "supabase"
+  },
+  "ss/supabase/permissive-policy": {
+    actor: "public_user",
+    lane: "database",
+    asset: databaseAsset,
+    permission: "write",
+    condition: "permissive_policy",
+    risk: "public_database_access",
+    provider: "supabase"
+  },
+  "ss/firebase/open-rules": {
+    actor: "public_user",
+    lane: "database",
+    asset: databaseAsset,
+    permission: "write",
+    condition: "open_rules",
+    risk: "public_database_access",
+    provider: "firebase"
+  },
+  "ss/client/firebase-admin-in-client": {
+    actor: "frontend_bundle",
+    lane: "env_variable",
+    asset: () => "firebase:admin_sdk",
+    permission: "admin",
+    condition: "client_exposed",
+    risk: "client_to_admin",
+    provider: "firebase"
+  },
+  "ss/convex/mutation-no-auth": {
+    actor: "public_user",
+    lane: "server_action",
+    asset: databaseAsset,
+    permission: "execute",
+    condition: "no_auth_check",
+    risk: "anonymous_write",
+    provider: "convex"
+  },
+  "ss/convex/internal-not-internal": {
+    actor: "public_user",
+    lane: "server_action",
+    asset: databaseAsset,
+    permission: "execute",
+    condition: "internal_function_public",
+    risk: "untrusted_admin_surface",
+    provider: "convex"
+  },
+  "ss/auth/api-route-no-auth": {
+    actor: "public_user",
+    lane: "http_route",
+    asset: routeAsset,
+    permission: "execute",
+    condition: "no_auth_or_signature",
+    risk: "anonymous_execute",
+    provider: "web"
+  },
+  "ss/auth/admin-route-unprotected": {
+    actor: "public_user",
+    lane: "http_route",
+    asset: routeAsset,
+    permission: "admin",
+    condition: "no_server_auth",
+    risk: "untrusted_admin_surface",
+    provider: "web"
+  },
+  "ss/auth/client-only-guard": {
+    actor: "authenticated_user",
+    lane: "http_route",
+    asset: routeAsset,
+    permission: "admin",
+    condition: "client_only_role_check",
+    risk: "client_to_admin",
+    provider: "web"
+  },
+  "ss/auth/cors-wildcard-with-credentials": {
+    actor: "public_user",
+    lane: "http_route",
+    asset: routeAsset,
+    permission: "execute",
+    condition: "wildcard_origin_with_credentials",
+    risk: "cors_credential_theft",
+    provider: "web"
+  },
+  "ss/server/route-no-auth": {
+    actor: "public_user",
+    lane: "self_hosted_server",
+    asset: routeAsset,
+    permission: "execute",
+    condition: "no_auth_middleware",
+    risk: "anonymous_execute",
+    provider: "self-hosted"
+  },
+  "ss/deploy/public-env-secret": {
+    actor: "deploy_platform",
+    lane: "deploy_config",
+    asset: envAsset,
+    permission: "read",
+    condition: "public_or_build_exposed",
+    risk: "deploy_secret_exposure",
+    provider: "deploy"
+  },
+  "ss/client/server-secret-env-in-client": {
+    actor: "frontend_bundle",
+    lane: "env_variable",
+    asset: envAsset,
+    permission: "read",
+    condition: "client_exposed",
+    risk: "client_to_server_secret",
+    provider: "web"
+  },
+  "ss/client/next-public-secret": {
+    actor: "frontend_bundle",
+    lane: "env_variable",
+    asset: envAsset,
+    permission: "read",
+    condition: "next_public_exposed",
+    risk: "client_to_server_secret",
+    provider: "nextjs"
+  },
+  "ss/secrets/env-file-committed": {
+    actor: "ai_agent",
+    lane: "filesystem",
+    asset: () => ".env",
+    permission: "modify",
+    condition: "committed_or_staged",
+    risk: "agent_to_secret",
+    provider: "agent"
+  },
+  "ss/agent/secrets-in-agent-files": {
+    actor: "ai_agent",
+    lane: "agent_tooling",
+    asset: routeAsset,
+    permission: "read",
+    condition: "agent_instruction_exposes_secret",
+    risk: "agent_to_secret",
+    provider: "agent"
+  },
+  "ss/agent/mcp-inline-credentials": {
+    actor: "ai_agent",
+    lane: "agent_tooling",
+    asset: routeAsset,
+    permission: "read",
+    condition: "inline_mcp_credentials",
+    risk: "agent_to_secret",
+    provider: "agent"
+  },
+  "ss/agent/overbroad-permissions": {
+    actor: "ai_agent",
+    lane: "agent_tooling",
+    asset: routeAsset,
+    permission: "execute",
+    condition: "overbroad_tool_permission",
+    risk: "agent_to_secret",
+    provider: "agent"
+  },
+  "ss/deps/postinstall-script": {
+    actor: "dependency",
+    lane: "package_install",
+    asset: packageAsset,
+    permission: "execute",
+    condition: "install_lifecycle_script",
+    risk: "dependency_to_shell",
+    provider: "npm"
+  },
+  "ss/deps/unpinned-spec": {
+    actor: "dependency",
+    lane: "package_install",
+    asset: packageAsset,
+    permission: "install",
+    condition: "latest_or_star",
+    risk: "unreproducible_dependency",
+    provider: "npm"
+  },
+  "ss/deps/known-vuln": {
+    actor: "dependency",
+    lane: "package_install",
+    asset: packageAsset,
+    permission: "execute",
+    condition: "known_vulnerability",
+    risk: "known_vulnerable_dependency",
+    provider: "npm"
+  },
+  "ss/deps/hallucinated-package": {
+    actor: "dependency",
+    lane: "package_install",
+    asset: packageAsset,
+    permission: "install",
+    condition: "package_not_found",
+    risk: "unknown_package",
+    provider: "npm"
+  },
+  "ss/deps/no-lockfile": {
+    actor: "dependency",
+    lane: "package_install",
+    asset: () => "lockfile",
+    permission: "install",
+    condition: "missing_lockfile",
+    risk: "unreproducible_dependency",
+    provider: "npm"
+  },
+  "ss/secrets/hardcoded-provider-key": {
+    actor: "server_runtime",
+    lane: "env_variable",
+    asset: envAsset,
+    permission: "read",
+    condition: "hardcoded",
+    risk: "server_secret_exposure",
+    provider: "provider"
+  },
+  "ss/secrets/generic-credential-assignment": {
+    actor: "server_runtime",
+    lane: "env_variable",
+    asset: envAsset,
+    permission: "read",
+    condition: "credential_assignment",
+    risk: "server_secret_exposure",
+    provider: "provider"
+  },
+  "ss/secrets/private-key-file": {
+    actor: "server_runtime",
+    lane: "filesystem",
+    asset: routeAsset,
+    permission: "read",
+    condition: "private_key_file",
+    risk: "server_secret_exposure",
+    provider: "provider"
+  }
+};
+function fallbackTemplate(finding) {
+  if (finding.finding.file.includes("coolify") || finding.finding.file.includes("docker")) {
+    return {
+      actor: "deploy_platform",
+      lane: "deploy_config",
+      asset: routeAsset,
+      permission: "execute",
+      condition: "deploy_config_change",
+      risk: "deploy_secret_exposure",
+      provider: "deploy"
+    };
+  }
+  return {
+    actor: "server_runtime",
+    lane: "filesystem",
+    asset: routeAsset,
+    permission: "read",
+    condition: "scanner_finding",
+    risk: "server_secret_exposure",
+    provider: "generic"
+  };
+}
+function toLane(finding) {
+  const template = RULE_TEMPLATES[finding.finding.rule_id] ?? fallbackTemplate(finding);
+  return {
+    actor: template.actor,
+    lane: template.lane,
+    asset: template.asset(finding),
+    permission: template.permission,
+    condition: template.condition,
+    risk: template.risk,
+    severity: finding.finding.severity,
+    provider: template.provider,
+    source: {
+      rule_id: finding.finding.rule_id,
+      title: finding.finding.title,
+      file: finding.finding.file,
+      line: finding.finding.line,
+      evidence: finding.spans[0]?.evidence
+    },
+    fix: finding.finding.fix
+  };
+}
+function countBy(items, pick) {
+  const counts = {};
+  for (const item of items) counts[pick(item)] = (counts[pick(item)] ?? 0) + 1;
+  return counts;
+}
+function buildAccessMap(result) {
+  const lanes = result.findings.map(toLane).sort(
+    (a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || a.actor.localeCompare(b.actor) || a.asset.localeCompare(b.asset) || a.source.rule_id.localeCompare(b.source.rule_id)
+  );
+  return {
+    schema: "seamshield.access-map/v1",
+    target: result.target,
+    policy_bundle_digest: result.policyBundleDigest,
+    summary: {
+      lanes_total: lanes.length,
+      by_actor: countBy(lanes, (lane) => lane.actor),
+      by_risk: countBy(lanes, (lane) => lane.risk),
+      by_severity: countBy(lanes, (lane) => lane.severity)
+    },
+    lanes
+  };
+}
+function buildShipVerdict(result) {
+  const access = buildAccessMap(result);
+  const critical = access.lanes.filter((lane) => lane.severity === "block" || lane.severity === "high");
+  const warnings = access.lanes.filter((lane) => lane.severity === "warn" || lane.severity === "info");
+  return {
+    schema: "seamshield.ship/v1",
+    target: result.target,
+    verdict: critical.length > 0 ? "UNSAFE TO SHIP" : "SAFE TO SHIP",
+    exitCode: critical.length > 0 ? 1 : 0,
+    access,
+    critical,
+    warnings
+  };
+}
+function renderAccessJson(access) {
+  return JSON.stringify(access, null, 2);
+}
+var SEVERITY_COLOR = {
+  block: (s) => import_picocolors.default.red(s),
+  high: (s) => import_picocolors.default.magenta(s),
+  warn: (s) => import_picocolors.default.yellow(s),
+  info: (s) => import_picocolors.default.dim(s)
+};
+function renderLane(lane) {
+  return [
+    `  -> ${lane.lane} -> ${lane.asset}`,
+    `     permission: ${lane.permission}`,
+    `     condition: ${lane.condition}`,
+    `     risk: ${SEVERITY_COLOR[lane.severity](lane.risk)} (${lane.source.rule_id})`
+  ];
+}
+function renderAccessTable(access) {
+  const lines = [import_picocolors.default.bold("Access Map"), ""];
+  if (access.lanes.length === 0) {
+    lines.push(import_picocolors.default.green("No dangerous access lanes found."));
+    return lines.join("\n");
+  }
+  const actors = [...new Set(access.lanes.map((lane) => lane.actor))];
+  for (const actor of actors) {
+    lines.push(import_picocolors.default.bold(actor));
+    for (const lane of access.lanes.filter((candidate) => candidate.actor === actor)) {
+      lines.push(...renderLane(lane));
+    }
+    lines.push("");
+  }
+  lines.push(import_picocolors.default.dim(`policy bundle ${access.policy_bundle_digest.slice(0, 12)}`));
+  return lines.join("\n");
+}
+function renderShipTable(verdict) {
+  const lines = [import_picocolors.default.bold("SeamShield Ship Check"), "", `Verdict: ${verdict.verdict}`, ""];
+  if (verdict.critical.length > 0) {
+    lines.push(import_picocolors.default.red("Critical"));
+    verdict.critical.forEach((lane, i) => {
+      lines.push(
+        `${i + 1}. ${lane.actor} can ${lane.permission} ${lane.asset} (${lane.risk})`,
+        `   ${lane.source.file}:${lane.source.line} ${lane.source.rule_id}`
+      );
+    });
+    lines.push("");
+  }
+  if (verdict.warnings.length > 0) {
+    lines.push(import_picocolors.default.yellow("Warnings"));
+    verdict.warnings.forEach((lane, i) => {
+      lines.push(
+        `${i + 1}. ${lane.actor} can ${lane.permission} ${lane.asset} (${lane.risk})`,
+        `   ${lane.source.file}:${lane.source.line} ${lane.source.rule_id}`
+      );
+    });
+    lines.push("");
+  }
+  if (verdict.critical.length === 0 && verdict.warnings.length === 0) {
+    lines.push(import_picocolors.default.green("No dangerous access lanes found."), "");
+  }
+  lines.push("Next:", "npx seamshield access", "npx seamshield fix-plan");
+  return lines.join("\n");
+}
 function matchBasenamePattern(name, pattern) {
-  if (pattern.startsWith("*")) return name.endsWith(pattern.slice(1));
-  if (pattern.endsWith("*")) return name.startsWith(pattern.slice(0, -1));
+  if (pattern.includes("*")) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`).test(name);
+  }
   return name === pattern;
 }
 function fileMatchesRule(file, check) {
@@ -304,7 +750,38 @@ function promptFor(finding) {
     `Fix: ${finding.finding.fix.agent_prompt}`
   ].join("\n");
 }
-function buildFixPlan(result) {
+function rulesForAgent(agent) {
+  const base = [
+    "Do not print, rename, commit, or expose secret values.",
+    "Do not move server credentials into public/client env names.",
+    "Do not weaken authentication, authorization, database rules, storage rules, or CORS.",
+    "Preserve current user-facing behavior unless the risky access lane requires a safer boundary.",
+    "Re-run `npx seamshield ship --offline` after changes."
+  ];
+  if (agent === "codex") return [...base, "Use focused edits and run the repo's typecheck/tests before claiming done."];
+  if (agent === "claude") return [...base, "Respect existing CLAUDE.md project instructions and tool hooks."];
+  if (agent === "cursor") return [...base, "Respect existing Cursor rules and keep generated code inside the intended files."];
+  return base;
+}
+function lanePrompt(lane) {
+  return [
+    `## Issue`,
+    `${lane.actor} can ${lane.permission} ${lane.asset} through ${lane.lane}.`,
+    "",
+    `Risk: ${lane.risk}`,
+    `Condition: ${lane.condition}`,
+    `Source: ${lane.source.file}:${lane.source.line} (${lane.source.rule_id})`,
+    "",
+    `## Goal`,
+    lane.fix.summary,
+    "",
+    `## Steps`,
+    lane.fix.agent_prompt
+  ].join("\n");
+}
+function buildFixPlan(result, options = {}) {
+  const agent = options.agent ?? "generic";
+  const access = buildAccessMap(result);
   const items = result.findings.map((finding) => ({
     rule_id: finding.finding.rule_id,
     severity: finding.finding.severity,
@@ -318,19 +795,31 @@ function buildFixPlan(result) {
   return {
     schema: "seamshield.fix-plan/v1",
     target: result.target,
+    agent,
     policy_bundle_digest: result.policyBundleDigest,
-    summary: { findings_total: result.findings.length },
+    summary: { findings_total: result.findings.length, access_lanes_total: access.lanes.length },
     items,
+    access_lanes: access.lanes,
     agent_markdown: [
       "# SeamShield Fix Plan",
       "",
-      "Apply these fixes without exposing or logging secret values.",
+      ...rulesForAgent(agent).map((rule) => `- ${rule}`),
       "",
-      ...items.map((item) => item.agent_prompt),
+      ...access.lanes.map(lanePrompt),
       ""
     ].join("\n")
   };
 }
+function dateStamp(now = /* @__PURE__ */ new Date()) {
+  return now.toISOString().slice(0, 10);
+}
+function writeMarkdownFixPlan(result, options = {}) {
+  const dir = join22(result.target, ".seamshield", "fix-plans");
+  mkdirSync(dir, { recursive: true });
+  const path = join22(dir, `${dateStamp(options.now)}-critical-access-risks.md`);
+  writeFileSync(path, buildFixPlan(result, { agent: options.agent }).agent_markdown);
+  return path;
+}
 var PatternSchema = z2.object({
   name: z2.string().min(1),
   regex: z2.string().min(1)
@@ -474,42 +963,42 @@ function renderSarif(result) {
     2
   );
 }
-var SEVERITY_COLOR = {
-  block: (s) => import_picocolors.default.red(s),
-  high: (s) => import_picocolors.default.magenta(s),
-  warn: (s) => import_picocolors.default.yellow(s),
-  info: (s) => import_picocolors.default.dim(s)
+var SEVERITY_COLOR2 = {
+  block: (s) => import_picocolors2.default.red(s),
+  high: (s) => import_picocolors2.default.magenta(s),
+  warn: (s) => import_picocolors2.default.yellow(s),
+  info: (s) => import_picocolors2.default.dim(s)
 };
 function renderTable(result) {
   const lines = [];
   lines.push(
-    `${import_picocolors.default.bold(`SeamShield v${result.engineVersion}`)}${import_picocolors.default.dim(
+    `${import_picocolors2.default.bold(`SeamShield v${result.engineVersion}`)}${import_picocolors2.default.dim(
       ` \u2014 ${result.filesScanned} files, ${result.rulesLoaded} rules`
     )}`
   );
   lines.push("");
   if (result.findings.length === 0) {
-    lines.push(import_picocolors.default.green("\u2713 No findings."));
+    lines.push(import_picocolors2.default.green("\u2713 No findings."));
   } else {
     for (const f of result.findings) {
-      const sev = SEVERITY_COLOR[f.finding.severity](
+      const sev = SEVERITY_COLOR2[f.finding.severity](
         f.finding.severity.toUpperCase().padEnd(5)
       );
-      lines.push(`${sev} ${f.finding.rule_id}  ${import_picocolors.default.bold(`${f.finding.file}:${f.finding.line}`)}`);
+      lines.push(`${sev} ${f.finding.rule_id}  ${import_picocolors2.default.bold(`${f.finding.file}:${f.finding.line}`)}`);
       lines.push(`      ${f.finding.title}`);
       const evidence = f.spans[0]?.evidence;
-      if (evidence) lines.push(import_picocolors.default.dim(`      evidence: ${evidence}`));
-      lines.push(`      ${import_picocolors.default.cyan("fix:")} ${f.finding.fix.summary}`);
+      if (evidence) lines.push(import_picocolors2.default.dim(`      evidence: ${evidence}`));
+      lines.push(`      ${import_picocolors2.default.cyan("fix:")} ${f.finding.fix.summary}`);
       lines.push("");
     }
     const counts = /* @__PURE__ */ new Map();
     for (const f of result.findings) {
       counts.set(f.finding.severity, (counts.get(f.finding.severity) ?? 0) + 1);
     }
-    const parts = [...counts.entries()].map(([sev, n]) => SEVERITY_COLOR[sev](`${n} ${sev}`));
-    lines.push(`${import_picocolors.default.bold(`${result.findings.length} findings`)} (${parts.join(", ")})`);
+    const parts = [...counts.entries()].map(([sev, n]) => SEVERITY_COLOR2[sev](`${n} ${sev}`));
+    lines.push(`${import_picocolors2.default.bold(`${result.findings.length} findings`)} (${parts.join(", ")})`);
   }
-  lines.push(import_picocolors.default.dim(`policy bundle ${result.policyBundleDigest.slice(0, 12)}`));
+  lines.push(import_picocolors2.default.dim(`policy bundle ${result.policyBundleDigest.slice(0, 12)}`));
   return lines.join("\n");
 }
 var DEP_FIELDS = [
@@ -693,12 +1182,6 @@ function checkNoLockfile(rule, ctx) {
   }
   return [buildFinding(rule, "package.json", 1, "no lockfile found next to package.json", ctx)];
 }
-var SEVERITY_RANK = {
-  block: 0,
-  high: 1,
-  warn: 2,
-  info: 3
-};
 var SKIP_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
   ".git",
@@ -707,6 +1190,8 @@ var SKIP_DIRS = /* @__PURE__ */ new Set([
   "build",
   "out",
   "coverage",
+  "target",
+  ".gradle",
   ".turbo",
   ".vercel",
   ".cache",
@@ -714,8 +1199,6 @@ var SKIP_DIRS = /* @__PURE__ */ new Set([
 ]);
 var MAX_FILE_BYTES = 1e6;
 function walk(root) {
-  const gitFiles = gitTrackedAndUnignoredFiles(root);
-  if (gitFiles) return gitFiles;
   const files = [];
   const visit = (dir) => {
     let entries;
@@ -746,15 +1229,6 @@ function walk(root) {
   visit(root);
   return files;
 }
-function gitTrackedAndUnignoredFiles(root) {
-  const result = spawnSync2(
-    "git",
-    ["-C", root, "ls-files", "--cached", "--others", "--exclude-standard"],
-    { encoding: "utf8", timeout: 1500 }
-  );
-  if (result.error || result.status !== 0 || typeof result.stdout !== "string") return null;
-  return result.stdout.split("\n").filter(Boolean).filter((rel) => !rel.split("/").some((part) => SKIP_DIRS.has(part))).filter((rel) => rel !== ".claude/worktrees" && !rel.includes("/.claude/worktrees/")).filter((rel) => rel !== ".worktrees" && !rel.startsWith(".worktrees/")).map((rel) => ({ abs: join6(root, rel), rel }));
-}
 var FileCache = class {
   cache = /* @__PURE__ */ new Map();
   read(abs) {
@@ -798,7 +1272,14 @@ function scan(target, options = {}) {
       throw new Error(`${rule.id}: unknown builtin check "${rule.check.builtin}"`);
     }
   }
-  findings = findings.filter((f) => !isIgnored(f.finding.file, config.ignorePrefixes));
+  findings = findings.filter((f) => !isIgnored(f.finding.file, config.ignorePrefixes)).filter(
+    (f) => !isSuppressedByConfig(
+      f.finding.rule_id,
+      f.finding.file,
+      f.finding.line,
+      config.suppressions
+    )
+  ).map((f) => refineFinding(f, cache, files));
   findings.sort(
     (a, b) => SEVERITY_RANK[a.finding.severity] - SEVERITY_RANK[b.finding.severity] || a.finding.file.localeCompare(b.finding.file) || a.finding.line - b.finding.line || a.finding.rule_id.localeCompare(b.finding.rule_id)
   );
@@ -846,7 +1327,12 @@ async function scanAsync(target, options = {}) {
     }
   }
   result.findings = [...result.findings, ...dependencyFindings].filter(
-    (f) => !isIgnored(f.finding.file, config.ignorePrefixes)
+    (f) => !isIgnored(f.finding.file, config.ignorePrefixes) && !isSuppressedByConfig(
+      f.finding.rule_id,
+      f.finding.file,
+      f.finding.line,
+      config.suppressions
+    )
   );
   result.findings.sort(
     (a, b) => SEVERITY_RANK[a.finding.severity] - SEVERITY_RANK[b.finding.severity] || a.finding.file.localeCompare(b.finding.file) || a.finding.line - b.finding.line || a.finding.rule_id.localeCompare(b.finding.rule_id)
@@ -855,6 +1341,22 @@ async function scanAsync(target, options = {}) {
   result.networkSkipped = false;
   return result;
 }
+function refineFinding(finding, cache, files) {
+  if (finding.finding.rule_id !== "ss/auth/client-only-guard") return finding;
+  const file = files.find((candidate) => candidate.rel === finding.finding.file);
+  if (!file) return finding;
+  const content = cache.read(file.abs);
+  if (!content) return finding;
+  const hasServerDataBoundary = /\b(?:fetch|axios|useQuery|useMutation|useAction|api\.|convex|server action|route\.ts|\/api\/)\b/i.test(
+    content
+  );
+  if (hasServerDataBoundary) return finding;
+  return {
+    ...finding,
+    finding: { ...finding.finding, severity: "info" },
+    decision: "scan"
+  };
+}
 function computeExitCode(findings, failOn) {
   if (failOn === "never") return 0;
   const threshold = SEVERITY_RANK[failOn];
@@ -908,13 +1410,21 @@ var pkg = JSON.parse(
   readFileSync6(new URL("../package.json", import.meta.url), "utf8")
 );
 var FORMATS = ["table", "json", "sarif"];
+var ACCESS_FORMATS = ["table", "json"];
 var FAIL_ON = ["block", "high", "warn", "never"];
-function assertOptions(opts) {
-  if (opts.format && !FORMATS.includes(opts.format)) {
-    console.error(`seamshield: unknown --format "${opts.format}" (expected: ${FORMATS.join(", ")})`);
+var FIX_AGENTS = ["claude", "cursor", "codex", "generic"];
+function assertChoice(value, allowed, label) {
+  if (value && !allowed.includes(value)) {
+    console.error(`seamshield: unknown --${label} "${value}" (expected: ${allowed.join(", ")})`);
     process.exitCode = 2;
     return false;
   }
+  return true;
+}
+function assertOptions(opts) {
+  if (!assertChoice(opts.format, FORMATS, "format")) {
+    return false;
+  }
   if (opts.failOn && !FAIL_ON.includes(opts.failOn)) {
     console.error(`seamshield: unknown --fail-on "${opts.failOn}" (expected: ${FAIL_ON.join(", ")})`);
     process.exitCode = 2;
@@ -946,6 +1456,20 @@ async function runScan(path, opts) {
     process.exitCode = 2;
   }
 }
+async function readScanForCommand(path, offline = true) {
+  if (!existsSync2(path)) {
+    console.error(`seamshield: path not found: ${path}`);
+    process.exitCode = 2;
+    return null;
+  }
+  try {
+    return await scanAsync(path, { failOn: "never", network: offline ? "off" : "on" });
+  } catch (error) {
+    console.error(`seamshield: scan failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 2;
+    return null;
+  }
+}
 function writeAgentContext(target, kind) {
   const body = [
     "# SEAMSHIELD",
@@ -960,24 +1484,65 @@ function writeAgentContext(target, kind) {
   ].join("\n");
   if (kind === "cursor") {
     const out2 = join7(target, ".cursor", "rules", "seamshield.mdc");
-    mkdirSync(dirname3(out2), { recursive: true });
-    writeFileSync(out2, body);
+    mkdirSync3(dirname3(out2), { recursive: true });
+    writeFileSync3(out2, body);
     return out2;
   }
   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}`;
-  writeFileSync(out, next.endsWith("\n") ? next : `${next}
+  writeFileSync3(out, next.endsWith("\n") ? next : `${next}
 `);
   return out;
 }
+function readTriageConfig(target) {
+  const path = join7(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));
+  return out;
+}
+async function writeTriageSuppressions(path, opts) {
+  const target = resolve2(path);
+  const result = await readScanForCommand(target, !opts.online);
+  if (!result) return;
+  const config = readTriageConfig(target);
+  const suppress = config.suppress ?? [];
+  const existing = new Set(suppress.map((s) => `${s.rule}\0${s.file}\0${s.line ?? ""}`));
+  const candidates = result.findings.filter((finding) => {
+    if (opts.rule && finding.finding.rule_id !== opts.rule) return false;
+    if (!opts.includeBlock && finding.finding.severity === "block") return false;
+    return true;
+  });
+  for (const finding of candidates) {
+    const entry = {
+      rule: finding.finding.rule_id,
+      file: finding.finding.file,
+      line: finding.finding.line,
+      reason: opts.reason ?? "triaged false positive"
+    };
+    const key = `${entry.rule}\0${entry.file}\0${entry.line}`;
+    if (existing.has(key)) continue;
+    suppress.push(entry);
+    existing.add(key);
+  }
+  config.suppress = suppress;
+  const out = writeTriageConfig(target, config);
+  console.log(out);
+  console.log(`Suppressed ${candidates.length} current finding(s).`);
+}
 function currentBin() {
   return fileURLToPath2(import.meta.url);
 }
 function installGuard(target) {
   const settingsPath = join7(target, ".claude", "settings.json");
-  mkdirSync(dirname3(settingsPath), { recursive: true });
+  mkdirSync3(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`;
@@ -988,7 +1553,7 @@ function installGuard(target) {
     }
   ];
   settings.hooks = hooks;
-  writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}
+  writeFileSync3(settingsPath, `${JSON.stringify(settings, null, 2)}
 `);
   return settingsPath;
 }
@@ -1025,7 +1590,7 @@ function bashDecision(command) {
     const name = command.match(/npm\s+(?:i|install|add)\s+(@?[\w.-]+\/?[\w.-]*)/)?.[1];
     if (name) {
       const encoded = name.startsWith("@") ? name.replace("/", "%2F") : name;
-      const res = spawnSync3("curl", ["-fsSI", `https://registry.npmjs.org/${encoded}`], {
+      const res = spawnSync2("curl", ["-fsSI", `https://registry.npmjs.org/${encoded}`], {
         encoding: "utf8",
         timeout: 750
       });
@@ -1051,8 +1616,8 @@ function guardCheck() {
     }
     const tempRoot = mkdtempSync(join7(tmpdir(), "seamshield-guard-"));
     const abs = join7(tempRoot, proposed.rel.replace(/^\/+/, ""));
-    mkdirSync(dirname3(abs), { recursive: true });
-    writeFileSync(abs, proposed.content);
+    mkdirSync3(dirname3(abs), { recursive: true });
+    writeFileSync3(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");
@@ -1068,8 +1633,8 @@ function guardCheck() {
   } catch (error) {
     const logPath = join7(process.cwd(), ".seamshield", "guard.log");
     try {
-      mkdirSync(dirname3(logPath), { recursive: true });
-      writeFileSync(logPath, `${(/* @__PURE__ */ new Date()).toISOString()} ${String(error)}
+      mkdirSync3(dirname3(logPath), { recursive: true });
+      writeFileSync3(logPath, `${(/* @__PURE__ */ new Date()).toISOString()} ${String(error)}
 `, { flag: "a" });
     } catch {
     }
@@ -1081,7 +1646,23 @@ program.name("seamshield").description("Security scanner for AI-generated apps:
 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) => {
   return runScan(path, opts);
 });
-program.command("fix-plan").description("Write .seamshield/fix-plan.json with agent-ready fix prompts").argument("[path]", "directory to scan", ".").option("--offline", "skip npm registry and OSV network checks").action(async (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;
+  const verdict = buildShipVerdict(result);
+  console.log(renderShipTable(verdict));
+  process.exitCode = verdict.exitCode;
+});
+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);
+  if (!result) return;
+  const access = buildAccessMap(result);
+  console.log(opts.format === "json" ? renderAccessJson(access) : renderAccessTable(access));
+  process.exitCode = 0;
+});
+program.command("fix-plan").description("Write agent-ready fix prompts for dangerous access lanes").argument("[path]", "directory to scan", ".").option("--offline", "skip npm registry and OSV network checks").option("--agent <agent>", "target agent: claude | cursor | codex | generic", "generic").action(async (path, opts) => {
+  if (!assertChoice(opts.agent, FIX_AGENTS, "agent")) return;
   if (!existsSync2(path)) {
     console.error(`seamshield: path not found: ${path}`);
     process.exitCode = 2;
@@ -1089,12 +1670,24 @@ program.command("fix-plan").description("Write .seamshield/fix-plan.json with ag
   }
   const result = await scanAsync(path, { network: opts.offline ? "off" : "on" });
   const out = join7(resolve2(path), ".seamshield", "fix-plan.json");
-  mkdirSync(dirname3(out), { recursive: true });
-  writeFileSync(out, `${JSON.stringify(buildFixPlan(result), null, 2)}
+  mkdirSync3(dirname3(out), { recursive: true });
+  writeFileSync3(out, `${JSON.stringify(buildFixPlan(result, { agent: opts.agent }), null, 2)}
 `);
+  const markdownOut = writeMarkdownFixPlan(result, { agent: opts.agent });
   console.log(out);
+  console.log(markdownOut);
   process.exitCode = result.exitCode;
 });
+program.command("learn").description("Update local controls from vulnerability intelligence without uploading source").option("--source <path-or-url>", "future rule/control bundle source").action((opts) => {
+  console.log("SeamShield Learn");
+  console.log("Status: local rule/control updates are not wired yet.");
+  console.log("Privacy: no source code was read or uploaded.");
+  if (opts.source) console.log(`Requested source: ${opts.source}`);
+  process.exitCode = 0;
+});
+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) => {
   const target = resolve2(path);
   const kind = opts.cursor ? "cursor" : "claude";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seamshield",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Security scanner for AI-generated apps: finds the flaws vibecoded projects predictably ship",
   "type": "module",
   "license": "MIT",
@@ -24,16 +24,18 @@
     "nextjs",
     "supabase",
     "firebase",
+    "convex",
+    "vercel",
+    "coolify",
     "claude-code",
     "cursor",
     "osv",
     "sarif"
   ],
   "bin": {
-    "seamshield": "dist/index.js"
+    "seamshield": "./dist/index.js"
   },
   "files": [
-    "README.md",
     "dist",
     "rules",
     "schemas"
@@ -41,22 +43,21 @@
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --clean && tsc -p tsconfig.build.json && rm -rf rules schemas && cp -R ../rules/rules ../rules/schemas .",
-    "prepack": "pnpm run build",
-    "test": "vitest run"
-  },
   "dependencies": {
     "commander": "^14.0.0",
     "yaml": "^2.5.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@seamshield/core": "workspace:*",
-    "@seamshield/rules": "workspace:*",
     "@types/node": "^22.0.0",
     "tsup": "^8.3.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "@seamshield/core": "0.1.0",
+    "@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 .",
+    "test": "vitest run"
   }
-}
+}

package/rules/ss-auth-api-route-no-auth.yaml

@@ -11,9 +11,11 @@ check:
   include:
     path_contains: ["/api/"]
     extensions: [".ts", ".js", ".tsx", ".jsx"]
+  exclude:
+    basenames: ["_*.ts", "_*.js", "_*.tsx", "_*.jsx"]
   patterns:
     - name: auth-or-signature-markers
-      regex: "auth|Auth|session|Session|currentUser|getUser|clerk|Clerk|jwt|JWT|cookie|Cookie|bearer|Bearer|signature|webhook|svix|x-api-key|apiKey|API_KEY|verif|rate[Ll]imit|public"
+      regex: "auth|Auth|session|Session|currentUser|getUser|clerk|Clerk|jwt|JWT|cookie|Cookie|bearer|Bearer|signature|webhook|svix|x-api-key|apiKey|API_KEY|verif|rate[Ll]imit|public|410|Gone"
 fix:
   summary: Authenticate the caller, or mark the route as intentionally public.
   agent_prompt: >

package/rules/ss-client-next-public-secret.yaml

@@ -20,14 +20,11 @@ check:
     basenames:
       - ".env*"
   exclude:
-    dirs:
-      - "scripts"
-      - "test"
-      - "tests"
-      - "__tests__"
+    basenames:
+      - "seamshield-release-gate.mjs"
   patterns:
     - name: next-public-secret-name
-      regex: "(?:^\\s*|process\\.env\\.|import\\.meta\\.env\\.)(NEXT_PUBLIC_[A-Z0-9_]*(?:SECRET|SERVICE_ROLE|PRIVATE|PASSWORD|ADMIN)[A-Z0-9_]*)"
+      regex: "NEXT_PUBLIC_[A-Z0-9_]*(?:SECRET|SERVICE_ROLE|PRIVATE|PASSWORD|ADMIN)[A-Z0-9_]*"
 fix:
   summary: Rename the variable to drop the NEXT_PUBLIC_ prefix and read it only on the server.
   agent_prompt: >

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|internalMutation"
+      regex: "ctx\\.auth|getAuthUserId|getUserIdentity|requireAuth|requireInternalToken|getCaller|requireRole|requireAdmin|internalMutation|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-deploy-public-env-secret.yaml

@@ -0,0 +1,29 @@
+id: ss/deploy/public-env-secret
+severity: high
+title: Deploy config exposes a secret as a public env var
+description: >
+  A deploy or self-hosting config exposes a secret-looking value through a
+  public/client env namespace. Public env values can be embedded into builds,
+  logs, previews, or frontend bundles.
+framework_ref: AI_AGENT_DROP_IN.md#default-security-stance
+check:
+  type: regex
+  include:
+    basenames:
+      - "coolify.yaml"
+      - "coolify.yml"
+      - "docker-compose.yml"
+      - "docker-compose.yaml"
+      - "vercel.json"
+      - ".env"
+      - ".env.production"
+  patterns:
+    - name: public-secret-env
+      regex: "(?:NEXT_PUBLIC_|VITE_|PUBLIC_)[A-Z0-9_]*(?:SECRET|PRIVATE|PASSWORD|SERVICE_ROLE|API_KEY|TOKEN)[A-Z0-9_]*"
+fix:
+  summary: Move the secret to a server-only environment variable.
+  agent_prompt: >
+    Remove this value from the public/client env namespace. Put the
+    credential in a server-only environment variable, update code to read it
+    only from server-side handlers or workers, and rotate the exposed value
+    if it may have reached a build artifact or log.

package/rules/ss-deps-postinstall-script.yaml

@@ -0,0 +1,22 @@
+id: ss/deps/postinstall-script
+severity: warn
+title: Dependency install lifecycle script can execute shell commands
+description: >
+  npm lifecycle scripts such as postinstall run during dependency
+  installation. In AI-built apps this creates a supply-chain lane from a
+  dependency or pasted package.json change into local shell execution.
+framework_ref: AI_AGENT_DROP_IN.md#supply-chain-stance
+check:
+  type: regex
+  include:
+    basenames: ["package.json"]
+  patterns:
+    - name: install-lifecycle-script
+      regex: "\"(?:preinstall|install|postinstall)\"\\s*:"
+fix:
+  summary: Remove install lifecycle scripts unless they are reviewed and required.
+  agent_prompt: >
+    Review why this install lifecycle script is needed. If it is not
+    required, remove it. If it is required, pin the dependency or script
+    owner, document the command, and make sure it cannot download or execute
+    unreviewed remote code.

package/rules/ss-server-route-no-auth.yaml

@@ -0,0 +1,24 @@
+id: ss/server/route-no-auth
+severity: warn
+title: Self-hosted server route with no recognizable auth middleware
+description: >
+  An Express, Fastify, or Hono route handler contains no recognizable auth,
+  signature, token, or public-route marker. Review whether this self-hosted
+  server endpoint should be callable by anyone.
+framework_ref: AI_AGENT_DROP_IN.md#default-security-stance
+check:
+  type: absence
+  include:
+    extensions: [".ts", ".js", ".tsx", ".jsx", ".mjs"]
+    path_contains: ["server", "api", "routes"]
+  file_contains: "\\b(?:app|router|server)\\.(?:get|post|put|patch|delete|route)\\s*\\("
+  patterns:
+    - name: server-auth-markers
+      regex: "auth|Auth|session|Session|jwt|JWT|bearer|Bearer|cookie|Cookie|signature|webhook|x-api-key|apiKey|API_KEY|requireAuth|verify|public|health"
+fix:
+  summary: Add auth middleware or mark the route as intentionally public.
+  agent_prompt: >
+    Decide whether this server route should be public. If not, add auth,
+    API-key, session, or webhook-signature verification before the handler
+    does work. If it is intentionally public, add a short public-route
+    comment and a seamshield-ignore for this rule.