canship 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,114 @@
+# canship
+
+canship is a read-only static scanner for JavaScript and TypeScript web projects. It detects exposed credentials, misuse of public environment variables, and access-control misconfigurations in Next.js, Vite, Nuxt, Create React App, Expo, Supabase, and Firebase projects.
+
+The scan does not execute project code, upload content, or initiate network requests. The npm package has no runtime dependencies. When scanning a Git repository, canship reads only the local working tree and local commit history.
+
+```bash
+npx canship
+```
+
+Node.js 18 or later is required. Git is optional; only commit-history checks require a local Git installation and a readable repository. If canship is not already in the npm cache, `npx` may download it from the npm registry before the scan starts; that download is performed by npm and is not part of the scan.
+
+[简体中文](./README.zh-CN.md)
+
+## Checks
+
+| Check | Risk | Severity |
+|---|---|---|
+| Hardcoded credentials | A scanned file contains a recognised OpenAI, Anthropic, AWS, Stripe, GitHub, Slack, SendGrid, private-key, or database credential | P0 |
+| Private values in public environment variables | The value may be included in browser-delivered code | P0 |
+| Supabase `service_role` key reachable from client code | A `service_role` key can bypass Row Level Security (RLS) policies | P0 |
+| Git-tracked `.env` files | Recognised credentials remain in repository history; substantial unrecognised values may also produce a lower-confidence finding | P0 |
+| Supabase tables without RLS | A table exposed through the Supabase Data API lacks row-level access control | P1 |
+| Firebase rules allowing unconditional access | Unauthorised clients may be able to read or write data | P1 |
+| Next.js API routes accessing data without authentication | An unverified caller may access data or perform administrative operations | P0 / P1 |
+| CORS reflecting `Origin` while allowing credentials | Another site may access an endpoint with the user's credentials and read the response | P1 |
+
+Severity (P0, P1, P2) describes potential impact. Confidence (`certain`, `likely`) describes how strongly the code supports the finding. A `certain` P0/P1 finding blocks release and exits with status `1`; all other findings exit with status `2`.
+
+`Access-Control-Allow-Origin: *` combined with credentials is reported at P2 because browsers reject that configuration. A bare wildcard is not reported.
+
+For Git-tracked `.env` files, a recognised credential is reported at `certain` confidence. A substantial value that is not recognised but does not look public or placeholder-like is reported at `likely` confidence. Environment templates, public values, placeholders, and short settings do not trigger this Git rule solely because the file is tracked.
+
+## Usage
+
+```bash
+npx canship [path]
+```
+
+The current directory is scanned when no path is provided.
+
+| Option | Description |
+|---|---|
+| `-a`, `--all` | Show `likely` findings |
+| `--json` | Write machine-readable JSON |
+| `--fix-prompt` | Write remediation instructions for a coding assistant |
+| `--report[=file]` | Write a self-contained HTML report; defaults to `canship-report.html` |
+| `--best-effort` | Allow exit `0` when the scan is incomplete and has no findings; does not change the status of existing findings |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Show the version |
+
+`--json` and `--fix-prompt` are mutually exclusive. `--report` writes a separate file and may be combined with either mode.
+
+### Exit status
+
+| Status | Meaning |
+|---|---|
+| `0` | No findings at any confidence and the scan completed; with `--best-effort`, it may also mean an incomplete scan was accepted |
+| `1` | At least one `certain` P0/P1 finding |
+| `2` | Findings exist, but none is a confirmed P0/P1 release blocker |
+| `3` | Invalid arguments, a tool error, or an incomplete scan without `--best-effort` |
+
+When findings and an incomplete scan coexist, status `1` or `2` takes precedence. The JSON fields `partial`, `errors`, and `skipped` still preserve the incomplete-scan state.
+
+The default view expands only `certain` findings. Hidden `likely` findings still produce status `2`; the terminal and HTML report display a warning, and JSON reports the count in `hiddenLikely`. Use `--all` to include their full details.
+
+### Excluding a file
+
+Add `canship-ignore-file` on a line by itself to exclude the entire file. The marker may be wrapped only in `//`, `#`, `--`, `*`, `/* */`, or `<!-- -->` comment syntax. Intentionally excluded files are listed in the report and do not make the scan incomplete.
+
+### Remediation instructions
+
+`--fix-prompt` separates code changes that a coding assistant can perform from actions that require the project maintainer, such as rotating credentials, changing provider settings, or rewriting Git history.
+
+## Rule activation
+
+| Rule | Activation conditions |
+|---|---|
+| Public environment variables | The name starts with `NEXT_PUBLIC_`, `VITE_`, `REACT_APP_`, `EXPO_PUBLIC_`, `NUXT_PUBLIC_`, `GATSBY_`, `VUE_APP_`, or `PUBLIC_` |
+| Git-tracked environment files | The target is inside a readable local Git repository whose `.git` metadata is inside the checkout or names it back; templates, public values, placeholders, and short settings are excluded, and at most the 100 most recent relevant revisions of each file are inspected |
+| Next.js API authentication | Only data-accessing handlers under `app/api/**` and `pages/api/**`; recognises enforcing authentication calls, identity conditions that control rejection, and middleware `matcher` coverage for the route |
+| Supabase RLS | The current project scope contains `supabase/`, an `@supabase/supabase-js` or `@supabase/ssr` import, or a `SUPABASE_URL`; table-related DDL is replayed across migrations within that project scope |
+| Other credential and configuration rules | Match known file formats and content patterns without requiring a specific front-end framework |
+
+## Known limitations
+
+- canship uses static heuristics and does not verify runtime behaviour. Custom authentication wrappers, dynamic configuration, and unsupported syntax can cause false positives or false negatives.
+- Detection and redaction use the same credential patterns. A credential that canship cannot recognise cannot be guaranteed to be masked; if another rule quotes the same line, the original value may appear in the report. Treat reports as internal material.
+- Entropy-based detection is intentionally not used because random identifiers, hashes, and ordinary Base64 text cannot be classified reliably from entropy alone.
+- Files are limited to 2 MiB, traversal to 16 directory levels, and output to 100 findings per file. Git history checks inspect at most the 100 most recent relevant revisions of each file. Reaching a limit is recorded explicitly.
+- Symbolic links are not followed and make the scan incomplete.
+- Nested Git repositories and submodules are not expanded by the parent scan. They are listed as skipped and the parent scan is marked incomplete.
+- A `.git` file may point outside the checkout. canship follows it only when the target names this checkout back, which is what git records for a linked worktree and for a submodule. Anything else is read as a redirect to an unrelated repository: file scanning continues, history checks are marked incomplete.
+- Google, Firebase, and Maps `AIza...` keys are treated as public identifiers. Their application and API restrictions exist in Google Cloud and cannot be verified from local source, so the key value alone is not reported as a credential leak.
+- Rate limiting, injection, dependency vulnerabilities, and business authorisation beyond caller authentication are outside the scan scope.
+
+A canship result describes only what the implemented rules observed in the files that were read. It is not proof that the project has no other security defects.
+
+## Planned
+
+`--probe` is not implemented. The planned mode would, after explicit confirmation, issue read-only verification requests to service endpoints found in local project configuration. The current release does not initiate network requests.
+
+## Contributing
+
+Every new or changed detection rule should include at least two fixtures: one that must be reported and one that must not. See [`test/fixtures/`](./test/fixtures/).
+
+```bash
+npm ci
+npm run prepublishOnly
+```
+
+## License
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,116 @@
+# canship
+
+canship 是面向 JavaScript/TypeScript Web 项目的只读静态扫描工具，用于发现凭据泄露、公开环境变量误用和访问控制配置错误。支持 Next.js、Vite、Nuxt、Create React App、Expo，以及使用 Supabase 或 Firebase 的项目。
+
+扫描过程不会执行被扫描项目的代码，不会上传内容或主动访问网络，也没有运行时 npm 依赖。扫描 Git 仓库时，只读取本地工作区和本地提交历史。
+
+```bash
+npx canship
+```
+
+要求 Node.js 18 或更高版本。项目无需使用 Git；只有提交历史检查依赖本机 Git 和可读取的本地仓库。npm 缓存中没有 canship 时，`npx` 可能先从 npm registry 下载软件包，这一步由 npm 执行，不属于扫描过程。
+
+[English](./README.md)
+
+## 检测范围
+
+| 检查项 | 风险 | 级别 |
+|---|---|---|
+| 硬编码凭据 | 当前扫描文件中包含已识别的 OpenAI、Anthropic、AWS、Stripe、GitHub、Slack、SendGrid、私钥或数据库连接凭据 | P0 |
+| 公开环境变量中的私密值 | 私密值可能被打包进浏览器代码 | P0 |
+| 客户端可访问 Supabase `service_role` key | `service_role` 可绕过 Row Level Security（RLS）策略 | P0 |
+| Git 跟踪的 `.env` 文件 | 已识别凭据会留在仓库历史中；未识别但内容仍像真实配置的文件也可能产生低置信度结果 | P0 |
+| Supabase 表未启用 RLS | 表经 Supabase Data API 暴露时缺少行级访问控制 | P1 |
+| Firebase 规则允许无条件访问 | 未经授权的客户端可能读取或写入数据 | P1 |
+| Next.js API route 访问数据但未鉴权 | 未验证调用方即可访问数据或执行管理操作 | P0 / P1 |
+| CORS 回显 `Origin` 且允许凭据 | 其他站点可能携带用户凭据访问接口并读取响应 | P1 |
+
+严重度（P0、P1、P2）表示潜在影响，置信度（`certain`、`likely`）表示规则对结论的确定程度。两者相互独立：`certain` 的 P0/P1 结果会阻止发布并返回退出码 `1`；其他结果返回退出码 `2`。
+
+`Access-Control-Allow-Origin: *` 与凭据同时出现时报告为 P2，因为浏览器会拒绝该组合；单独使用 `*` 不报告。
+
+对于 Git 跟踪的 `.env` 文件，已识别凭据按 `certain` 报告；未识别但值较长且不像公开值或占位符时按 `likely` 报告。环境变量模板、公开值、占位符和短设置不会仅因文件进入 Git 而触发这条规则。
+
+## 使用方式
+
+```bash
+npx canship [路径]
+```
+
+未提供路径时扫描当前目录。
+
+| 参数 | 说明 |
+|---|---|
+| `-a`, `--all` | 显示 `likely` 结果 |
+| `--json` | 输出机器可读的 JSON |
+| `--fix-prompt` | 输出可交给编程助手的修复说明 |
+| `--report[=文件]` | 生成自包含的 HTML 报告；默认写入 `canship-report.html` |
+| `--best-effort` | 扫描不完整且没有任何结果时允许退出 `0`；不会改变已有结果对应的退出码 |
+| `-h`, `--help` | 显示帮助 |
+| `-v`, `--version` | 显示版本 |
+
+`--json` 与 `--fix-prompt` 互斥。`--report` 写入独立文件，可以与其中任意一种组合。
+
+### 退出码
+
+| 退出码 | 含义 |
+|---|---|
+| `0` | 没有任何置信度的结果，且扫描完整；使用 `--best-effort` 时也可能表示接受了不完整扫描 |
+| `1` | 至少有一条 `certain` 的 P0/P1 结果 |
+| `2` | 存在结果，但没有已确认的 P0/P1 阻断项 |
+| `3` | 参数或工具错误，或者扫描不完整且未使用 `--best-effort` |
+
+如果结果与不完整扫描同时存在，退出码 `1` 或 `2` 优先。JSON 中的 `partial`、`errors` 和 `skipped` 字段仍会保留扫描不完整的信息。
+
+默认视图只展开 `certain` 结果。被隐藏的 `likely` 结果仍会使进程返回 `2`；终端和 HTML 报告会显示警告，JSON 通过 `hiddenLikely` 给出数量。使用 `--all` 可查看完整结果。
+
+### 排除文件
+
+在文件中单独添加一行 `canship-ignore-file` 可以排除整个文件。标记前后只允许出现 `//`、`#`、`--`、`*`、`/* */` 或 `<!-- -->` 注释符。被主动排除的文件会列入报告，但不会使扫描标记为不完整。
+
+### 修复说明
+
+`--fix-prompt` 将输出分为两部分：可以交给编程助手执行的代码修改，以及必须由项目维护者完成的操作，例如轮换密钥、修改服务端控制台配置或重写 Git 历史。
+
+当前扫描结果、HTML 报告和修复说明正文使用英文，JSON 字段名也使用英文。
+
+## 规则生效条件
+
+| 规则 | 生效条件 |
+|---|---|
+| 公开环境变量 | 变量名以 `NEXT_PUBLIC_`、`VITE_`、`REACT_APP_`、`EXPO_PUBLIC_`、`NUXT_PUBLIC_`、`GATSBY_`、`VUE_APP_` 或 `PUBLIC_` 开头 |
+| Git 凭据历史 | 目标位于可读取的本地 Git 仓库中，且 `.git` 元数据位于工作区内、或其目标反向指认本工作区；模板、公开值、占位符和短设置除外；每个文件最多检查最近 100 个相关版本 |
+| Next.js API 鉴权 | 仅检查 `app/api/**` 和 `pages/api/**`；识别明确的鉴权调用、控制拒绝响应的身份条件，以及覆盖该路由的 middleware `matcher` |
+| Supabase RLS | 当前子项目存在 `supabase/`、`@supabase/supabase-js`/`@supabase/ssr` 导入或 `SUPABASE_URL`；按子项目重放 migration 中与表相关的 DDL |
+| 其他凭据和配置规则 | 按已知文件格式和内容模式匹配，不要求特定前端框架 |
+
+## 已知限制
+
+- canship 是静态启发式扫描器，不验证运行时行为。自定义鉴权封装、动态配置和非标准语法可能产生误报或漏报。
+- 检测和脱敏使用同一套凭据特征。无法识别的凭据也无法保证脱敏；如果其所在行因其他规则被引用，原始值可能出现在报告中。因此报告应视为内部材料。
+- 工具不使用熵值检测，避免将随机 ID、哈希或普通 Base64 文本误判为凭据。
+- 单个文件最大读取 2 MiB，目录最大扫描深度为 16 层，单文件最多报告 100 条结果，Git 历史中单文件最多检查最近 100 个版本。触及上限时扫描会明确记录。
+- 符号链接不会被跟随，并会使扫描标记为不完整。
+- 嵌套 Git 仓库和子模块不会由父项目展开扫描。父项目会记录跳过项并标记扫描不完整。
+- `.git` 文件可能指向工作区之外。canship 只在目标反过来指认本工作区时才跟随——这正是 git 为链接工作树和子模块记录的形式；其余情况按"重定向到无关仓库"处理：文件扫描继续，历史检查标记为不完整。
+- Google/Firebase/Maps 的 `AIza...` key 被视为公开标识符。其应用和 API 限制保存在 Google Cloud，无法仅从本地源码判断，因此不会仅凭该值报告凭据泄露。
+- 不检查限流、注入、依赖漏洞，也不验证“调用方是否已登录”之外的业务授权逻辑。
+
+扫描结果只表示已实现规则在已读取文件中观察到的情况，不能证明项目不存在其他安全问题。
+
+## 计划
+
+`--probe` 尚未实现。计划在用户显式确认后，对项目本地配置中的服务地址发起只读验证请求。当前版本不会联网。
+
+## 参与开发
+
+新增或修改检测规则时，至少提供两个测试夹具：一个应当被检出，一个不应被检出。参见 [`test/fixtures/`](./test/fixtures/)。
+
+```bash
+npm ci
+npm run prepublishOnly
+```
+
+## 许可
+
+[MIT](./LICENSE)