@aldegad/safedeps 2.1.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 soohongkim
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,311 @@
+# Safedeps
+
+> Dependency install safety gate -- advisory checks, approved spec enforcement, and auto-rollback suspicious package installs in Claude Code and Codex CLI.
+
+## Why "reorg"?
+
+In blockchain networks, a **reorganization (reorg)** invalidates a sequence of blocks and reverts the chain to a previously confirmed safe state. `safedeps` applies the same principle to your `node_modules`: every install is treated as an unconfirmed block candidate until it passes a battery of supply-chain security checks. If anything looks wrong, the tool performs a **reorg** -- rolling back lock files, `package.json`, and `node_modules` to the last confirmed safe snapshot.
+
+No manual review. No leftover malicious code. Fully automatic.
+
+## Distribution Model
+
+Safedeps has two distribution surfaces:
+
+1. **Agent skill + hooks (canonical)** -- the repo itself is the skill folder. `SKILL.md`, hook scripts, provider/ledger libraries, and install helpers stay together in one directory.
+2. **npm package (CLI convenience)** -- `@aldegad/safedeps` installs the `safedeps` command. npm does **not** make Claude Code or Codex automatically discover the skill; after npm installation, users still need to run the hook/skill installer or manually register the skill folder.
+
+Use the GitHub release when you want the full skill/hook source tree as the canonical artifact. Use npm when you mainly want a versioned global CLI.
+
+## How It Works
+
+`safedeps` plugs into Claude Code and Codex CLI hooks as a pair of **PreToolUse** and **PostToolUse** hooks that wrap package install commands. The CLI owns provider lookups and the approved-spec ledger; hooks enforce that ledger and run post-install rollback checks.
+
+```
+                         PreToolUse                          PostToolUse
+                  (safedeps-pre-guard.sh)          (safedeps-post-verify.sh)
+                            |                                    |
+  install cmd ──> [ Advisory/ledger gate ] ──> [ Execute ] ──> [ Verify ]
+                     |            |                           |       |
+                  Block if      Snapshot                   Clean?  Suspicious?
+                  unapproved    lock/manifest files,        |       |
+                   or risky     package listings          Confirm  REORG
+                                                              |       |
+                                    |                       v       v
+                                    +--- parent_snapshot_id ──> confirmed
+                                                                    |
+                                                              Rollback to last
+                                                              confirmed snapshot
+```
+
+### Phase 1: Advisory Gate + Pre-flight (PreToolUse)
+
+Before an agent installs a dependency, it should run:
+
+```bash
+safedeps check <ecosystem> <pkg>@<version|range> --json
+```
+
+That command queries OSV (canonical), CISA KEV (hard-risk overlay), and GitHub Advisory (enrichment). Clean or safely narrowed specs are written to `~/.safedeps/approved-specs/`.
+
+When Claude Code or Codex CLI is about to run `npm install`, `pip install`, `cargo add`, `go get`, `gem install`, or similar commands, the guard hook:
+
+1. **Snapshots** the current `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, and `package.json` into `~/.safedeps/snapshots/`.
+2. **Records metadata** including a `parent_snapshot_id` linking to the previous confirmed snapshot (forming a chain, just like blocks).
+3. **Captures pre-install state** of `node_modules` (package listings and binary listings) for diff-based detection later.
+4. **Enforces the approved-spec ledger** for explicit `pkg@version` install commands.
+5. **Runs pre-flight checks** and **blocks** the command entirely if it detects:
+   - Typosquatting package names (`lod_sh`, `reacct`, `axois`, etc.)
+   - Non-standard `--registry` URLs (anything outside `registry.npmjs.org` and `registry.yarnpkg.com`)
+   - Piped remote execution patterns (`curl ... | bash`)
+   - Explicit disabling of install script safety (`npm config set ignore-scripts false`)
+
+If the ledger gate or a pre-flight check fails, the command is **blocked before execution** -- nothing is installed.
+
+### Phase 2: Post-install verification (`safedeps-post-verify.sh` -- PostToolUse)
+
+After the install command completes, the verify hook analyzes what changed:
+
+1. **Install script analysis** -- Scans newly added packages for `preinstall`, `install`, and `postinstall` scripts containing:
+   - Network access (`curl`, `wget`, `fetch`, `http`, `socket`, `dns`)
+   - Dynamic code execution (`eval`, `exec`, `spawn`, `child_process`, `Function()`)
+   - Sensitive path access (`~/.ssh`, `.env`, `.aws`, `credentials`)
+   - Obfuscated content (`base64`, `atob`, `Buffer.from`, hex/unicode escapes)
+
+2. **Lock file diff analysis** -- Compares the snapshotted lock file content against the post-install version:
+   - Resolved URLs pointing to non-standard registries
+   - Insecure protocols (`http://`, `git://`) in resolved URLs
+   - Unusually large dependency additions (>50 new resolved entries, indicating potential dependency confusion)
+
+3. **Binary inspection** -- Checks `node_modules/.bin/` for newly added native binaries (ELF, Mach-O, shared objects) that should not appear in a JavaScript project.
+
+### Phase 3: Confirm or Reorg
+
+- **All checks pass** -- The snapshot is marked as **confirmed** in `~/.safedeps/confirmed`. This becomes the new safe baseline.
+- **Any check fails** -- A **reorg** is triggered:
+  1. Lock files are restored from the last confirmed snapshot.
+  2. `package.json` is restored if it was modified.
+  3. `node_modules` is rebuilt via `npm ci` (or `npm install` as fallback) to purge any malicious artifacts.
+  4. The event is logged to `~/.safedeps/reorg.log`.
+  5. Claude Code receives a system message detailing the detected threats and rollback actions.
+
+## The Blockchain Analogy
+
+| Blockchain Concept | Safedeps Equivalent |
+|---|---|
+| **Block candidate** | Snapshot taken before `npm install` |
+| **Block validation** | Post-install security checks (scripts, lock diff, binaries) |
+| **Finality / confirmation** | Snapshot ID written to `~/.safedeps/confirmed` |
+| **Chain reorganization** | Rollback to last confirmed snapshot + `node_modules` rebuild |
+| **Parent hash linking** | `parent_snapshot_id` in each snapshot's `_meta.json` |
+| **Chain pruning** | Old unconfirmed snapshots cleaned up, confirmed chain preserved |
+
+## Detection Rules
+
+| Category | What it catches | Phase | Action |
+|---|---|---|---|
+| Typosquatting | Known misspelling patterns of popular packages | Pre-flight | **Block** |
+| Pipe execution | `curl \| bash`, `wget \| sh` | Pre-flight | **Block** |
+| Registry hijack | `--registry` pointing to unofficial sources | Pre-flight | **Block** |
+| Script safety bypass | `npm config set ignore-scripts false` | Pre-flight | **Block** |
+| Command indirection | `eval "npm install ..."`, subshell expansion, variable indirection | Pre-flight | **Guard** |
+| npx/dlx execution | `npx`, `pnpm dlx`, `yarn dlx` package execution | Pre-flight | **Guard** |
+| Malicious install scripts | Network calls, `eval`/`exec`, sensitive path access in hooks | Post-install | **Reorg** |
+| Obfuscated code | Base64, hex encoding, `Buffer.from` in install scripts | Post-install | **Reorg** |
+| Lock file tampering | Resolved URLs from non-standard registries | Post-install | **Reorg** |
+| Insecure protocols | `http://` or `git://` resolved URLs | Post-install | **Reorg** |
+| Dependency confusion | >50 new dependencies in a single install | Post-install | **Reorg** |
+| Native binaries | Compiled executables in `node_modules/.bin/` | Post-install | **Reorg** |
+
+## Installation
+
+### Prerequisites
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with hook support
+- `jq` -- JSON parsing (hooks exit gracefully if missing)
+- `shasum` or `sha256sum` -- hash computation
+- `file` (optional) -- binary detection
+
+```bash
+# macOS
+brew install jq
+
+# Ubuntu / Debian
+sudo apt-get install jq
+```
+
+### Setup From GitHub (Skill + Hooks)
+
+**1. Clone the repository:**
+
+```bash
+git clone https://github.com/aldegad/safedeps.git
+cd safedeps
+```
+
+**2. Install the skill + hooks:**
+
+```bash
+node scripts/install/install-safedeps-hooks.mjs
+```
+
+The installer is idempotent. It symlinks the skill into `~/.claude/skills/safedeps` and `~/.codex/skills/safedeps` when those roots exist, patches the matching hook config, and can also place `safedeps` on PATH through `~/.local/bin`.
+
+**3. Manual hook registration, if needed:**
+
+Edit `.claude/settings.json` (project-level) or `~/.claude/settings.json` (global):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/skills/safedeps/scripts/safedeps-pre-guard.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/skills/safedeps/scripts/safedeps-post-verify.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**4. Verify permissions:**
+
+```bash
+chmod +x ~/.claude/skills/safedeps/scripts/safedeps-pre-guard.sh
+chmod +x ~/.claude/skills/safedeps/scripts/safedeps-post-verify.sh
+```
+
+That's it. The guard activates automatically whenever Claude Code or Codex CLI runs a package install command.
+
+### Setup From npm (CLI First)
+
+```bash
+npm install -g @aldegad/safedeps
+safedeps version
+```
+
+npm puts `safedeps` on PATH through its standard `bin` entry. It does **not** register the agent skill or hooks for Claude Code / Codex. To enable the hooks from the npm-installed copy, run the installer from the installed package root:
+
+```bash
+cd "$(npm root -g)/@aldegad/safedeps"
+node scripts/install/install-safedeps-hooks.mjs
+```
+
+The installer is idempotent and only adds symlinks/hook entries. The `--link-bin` flag is **only useful when you installed via GitHub clone instead of npm** — npm already places the CLI on PATH, so the flag is redundant in this path.
+
+If you want the skill folder itself to be the canonical local source, prefer the GitHub setup above.
+
+### Daily Re-check With macOS Alerts
+
+Install a per-user LaunchAgent to re-check the approved-spec ledger once per day:
+
+```bash
+node scripts/install/install-safedeps-recheck-agent.mjs install --hour 9 --minute 0
+```
+
+This runs `safedeps re-check --json` against `~/.safedeps/approved-specs/`. It does not use LLM tokens; it only calls the advisory providers used by safedeps. If a new CVE/KEV is found, a spec is revoked, or a provider check is skipped, the wrapper writes `~/.safedeps/recheck-alerts.jsonl` and raises a macOS notification.
+
+Useful commands:
+
+```bash
+node scripts/install/install-safedeps-recheck-agent.mjs status
+node scripts/install/install-safedeps-recheck-agent.mjs uninstall
+tail -f ~/.safedeps/recheck.log
+```
+
+### Legacy State Migration
+
+If you used the old `npm-reorg-guard` state directory, migrate it once:
+
+```bash
+safedeps migrate
+```
+
+This copies missing state from `~/.npm-reorg-guard` into `~/.safedeps` and archives the legacy directory so there is no second active state root.
+
+## Real-World Attack Coverage
+
+`safedeps` is designed to catch the patterns behind real supply-chain incidents:
+
+- **`event-stream` (2018)** -- Malicious `postinstall` script with obfuscated code that exfiltrated cryptocurrency wallet keys. Caught by: install script analysis (obfuscation + network access detection).
+- **`ua-parser-js` hijack (2021)** -- Compromised package added a `preinstall` script that downloaded and executed cryptominers. Caught by: install script analysis (network access + code execution).
+- **`colors` / `faker` sabotage (2022)** -- While these were author-initiated, the abnormal dependency behavior would trigger the dependency explosion check.
+- **Typosquatting campaigns** -- Ongoing campaigns publishing packages like `crossenv` (instead of `cross-env`) or `babelcli` (instead of `babel-cli`). Caught by: pre-flight typosquatting pattern matching.
+- **Dependency confusion attacks** -- Internal package names published to the public registry with higher version numbers. Caught by: non-standard registry detection + large dependency count changes.
+
+## Logs and Snapshots
+
+| Path | Description |
+|---|---|
+| `~/.safedeps/reorg.log` | Full reorg event history with timestamps, reasons, and rolled-back files |
+| `~/.safedeps/confirmed` | Current confirmed (safe) snapshot ID |
+| `~/.safedeps/snapshots/` | All snapshot files (lock files, package.json copies, metadata) |
+
+```bash
+# View reorg history
+cat ~/.safedeps/reorg.log
+
+# Check current confirmed snapshot
+cat ~/.safedeps/confirmed
+
+# List all snapshots
+ls -la ~/.safedeps/snapshots/
+```
+
+Old unconfirmed snapshots are automatically pruned (keeping the 10 most recent), while the confirmed snapshot chain is always preserved.
+
+## Security Hardening
+
+`safedeps` includes multiple layers of defense against attacks targeting the guard itself:
+
+| Measure | What it prevents |
+|---|---|
+| **JSON-safe metadata** | `project_dir` is escaped via `jq -Rs` to prevent JSON injection in snapshot metadata |
+| **Path canonicalization** | `realpath`/`readlink -f` resolves symlinks and `..` traversal in `cwd` before use |
+| **Atomic state files** | Snapshot ID and project directory are written as a single JSON file, preventing TOCTOU races |
+| **Stale lock recovery** | Locks older than 60 seconds are automatically removed, preventing permanent DoS from `SIGKILL`/OOM |
+| **Project-scoped state** | Each project gets its own confirmed snapshot chain (`confirmed_${dir_hash}`), preventing cross-project interference |
+| **Restrictive permissions** | `umask 077` ensures `~/.safedeps/` is readable only by the owner |
+| **Indirection detection** | Commands using `eval`, `$()`, or backticks with package manager keywords are treated as install candidates |
+
+## Project Structure
+
+```
+safedeps/
+  bin/
+    safedeps      # CLI -- advisory gate, ledger, revoke, re-check
+  lib/
+    providers/    # OSV / CISA KEV / GHSA adapters
+    ledger/       # approved-spec ledger
+  scripts/
+    safedeps-pre-guard.sh       # PreToolUse hook -- snapshot + ledger enforcement
+    safedeps-post-verify.sh     # PostToolUse hook -- post-install verification + reorg
+    install/install-safedeps-hooks.mjs
+    install/install-safedeps-recheck-agent.mjs
+    install/migrate-safedeps-state.mjs
+    safedeps-recheck-alert.sh
+    test/
+  package.json
+  SKILL.md        # Claude Code / Codex skill manifest
+  LICENSE         # Apache-2.0
+```
+
+## License
+
+[Apache License 2.0](LICENSE)

package/ROADMAP.md

@@ -0,0 +1,131 @@
+# Safedeps Roadmap
+
+> 시간축 + 우선순위. **왜·어떻게** 는 `ARCHITECTURE.md`, **언제·뭐 먼저** 는 이 파일.
+
+---
+
+## 결정 SSoT
+
+**스코프 = 개발 의존성만** (npm / pip / cargo / go / gem / maven / nuget).
+OS-level (nginx / apt / brew / system binary) 은 **별도 도구로 분리**. SRP 측면 더 깔끔.
+
+근거: dev 의존성과 OS 패키지는 운영 결이 다름.
+- dev = "새 기능 → install 명령 → 매번 새 패키지 진입" (install 순간 게이트가 의미 큼).
+- OS = "기존 패키지 security update" (cron 주기 audit + RSS 알람이 더 맞음).
+
+→ safedeps = dev 의존성 install 단계 결.
+→ OS-level 은 별도 (가칭 `infra-cve-monitor` — 미래 v3+).
+
+---
+
+## v1 (출시 완료)
+
+**이름**: `npm-reorg-guard`
+**Status**: shipped as v1. GitHub repo has since been renamed to `aldegad/safedeps`.
+
+- npm ecosystem 전용.
+- PreToolUse hook (guard.sh): typosquat / curl|bash / 비표준 registry 등 **hardcoded pattern** 차단.
+- PostToolUse hook (verify.sh): lockfile diff + install script 검사 → 의심 시 **reorg** (rollback).
+- 외부 vuln DB 조회 0. self-contained.
+
+**한계**:
+- npm 만.
+- 알려진 CVE 검사 X (pattern matching 위주).
+- adversarial 회피 가능.
+
+---
+
+## v2 — Safedeps (현재 작업 중)
+
+**이름**: `safedeps`, 내부 engine = `reorg-guard` (v1 자산 보존).
+**Status**: `ARCHITECTURE.md` v2 작성 완료, v2.1 provider/ledger 구현 시작.
+
+### 핵심 변화
+- ecosystem 통합: npm / yarn / pnpm / pip (poetry, uv, pipenv) / cargo / go / gem / maven / nuget.
+- **외부 vuln DB 결합**: OSV.dev (primary) + CISA KEV (hard-risk overlay) + GHSA (cross-check). NVD / deps.dev / Snyk = enrichment.
+- **3-phase defense**:
+  1. Advisory Gate (`safedeps check`) — install 명령 *작성 전* vuln DB 조회 → 안전 spec 결정 → `~/.safedeps/approved-specs/<hash>.json` ledger 기록.
+  2. Hook Enforcement (`safedeps-pre-guard.sh`) — ledger 일치 검증.
+  3. Post-Install Reorg (`safedeps-post-verify.sh`) — v1 engine 그대로 (rollback fallback).
+- Approved spec **TTL** (30일) + **daily re-check** cron (새 CVE 발견 시 revoke + 알람).
+- **No silent fallback**: provider fail = fail-closed + `--allow-unverified` explicit override (observable).
+
+### 구현 마일스톤
+
+| 마일스톤 | 산출물 | 의존 |
+|---|---|---|
+| **v2.0-doc** ✅ | `ARCHITECTURE.md` v2 작성·push | — |
+| **v2.0-roadmap** ✅ | 이 문서 | — |
+| **v2.1-rename** ✅ | GitHub repo rename `aldegad/npm-reorg-guard` → `aldegad/safedeps` ✅. 로컬 repo/skill id/path `safedeps` ✅. `safedeps migrate` 로 legacy `~/.npm-reorg-guard` → `~/.safedeps` 이전 + legacy hook cleanup. | v2.0-doc |
+| **v2.1-providers** ✅ | `lib/providers/` 신규 — OSV / KEV / GHSA adapter. 단일 query interface. 응답 cache (TTL 24h). | — |
+| **v2.1-ledger** ✅ | `lib/ledger/` 신규 — approved spec JSON I/O (atomic write, hash 계산, TTL 검사). | v2.1-providers |
+| **v2.1-cli** ✅ | `bin/safedeps` 신규 — `check`, `ledger`, `revoke`, `re-check`, `migrate`, `version` 서브커맨드. | v2.1-providers, v2.1-ledger |
+| **v2.1-guard-patch** ✅ | `scripts/safedeps-pre-guard.sh` 갱신 — ledger 일치 검증 추가 + v1 pattern 유지. | v2.1-ledger |
+| **v2.1-verify-patch** ✅ | `scripts/safedeps-post-verify.sh` 갱신 — approved spec 과 lockfile diff 비교 추가 + v1 reorg 유지. | v2.1-ledger |
+| **v2.1-multi-ecosystem** ✅ | pip / cargo / go / gem / maven / nuget 명령 파싱 + lockfile snapshot. `safedeps-pre-guard.sh` 는 install 분류와 typosquat pattern 을 확장했고, `safedeps-post-verify.sh` 는 monitored dependency files 기준으로 rollback truth 를 공유한다. | v2.1-guard-patch |
+| **v2.1-hook-rename** ✅ | hook 파일 namespacing (`guard.sh` → `safedeps-pre-guard.sh`, `verify.sh` → `safedeps-post-verify.sh`) + cross-engine installer (`scripts/install/install-safedeps-hooks.mjs`, ~/.claude + ~/.codex 자동 등록, idempotent, --uninstall). | v2.1-cli |
+| **v2.1-recheck-cron** ✅ | daily re-check launchd — 전체 approved spec 재 query → 새 CVE/KEV/provider-skip 시 revoke + macOS 알림. | v2.1-providers, v2.1-ledger |
+| **v2.1-tests** ✅ | end-to-end 테스트 — fixture provider 응답 → 명령 시뮬레이션 → ledger / hook / re-check / migration 동작 검증. | 모든 v2.1 |
+| **v2.1-release** | npm package publish (`@aldegad/safedeps`) + GitHub release v2.1.0. | 모든 v2.1 |
+
+### 2026-05-18 릴리즈 전 정리 메모
+
+- npm package metadata 는 v2.1.0 기준으로 정합화한다 (`package.json` version + `bin.safedeps`).
+- `npm test` 는 release smoke suite 를 실행한다. full fixture E2E 는 `v2.1-tests` 후속으로 남긴다.
+- daily re-check 는 토큰을 쓰지 않는다. 알렉스가 opt-in 하면 macOS `launchd` user agent 로 `safedeps re-check --json` 을 매일 실행하는 구조가 기본이다. 네트워크는 OSV/CISA/GHSA provider query 에만 사용된다.
+- 실제 local background job 은 `scripts/install/install-safedeps-recheck-agent.mjs` 로 atomic install 한다. wrapper 는 `~/.safedeps/recheck.log` 와 `~/.safedeps/recheck-alerts.jsonl` 를 쓰고, 새 CVE/KEV/revoke/provider-skip 이 있으면 macOS notification 을 띄운다.
+
+### 후속 로드맵 — 전체 workspace inventory audit
+
+전체 repo/lockfile inventory scan 은 safedeps v2.1 daily re-check 와 분리한다. 후보 설계는 최초 one-shot inventory scan 으로 workspace 의 manifest/lockfile 을 발견하고, 사용자가 채택한 spec 만 approved ledger 또는 별도 inventory ledger 에 넣은 뒤 주기 re-check 대상으로 삼는 방식이다. 이렇게 해야 safedeps 의 현재 책임인 install approval gate 와 이미 디스크에 존재하는 dependency audit 의 책임 소재가 섞이지 않는다.
+
+### 우선순위
+
+1. v2.1-release: commit / tag / GitHub release / npm publish.
+
+---
+
+## v3 (미래 — 알렉스 결정 시점)
+
+- **plugin model** — 사용자 정의 provider (회사 내부 vuln DB, private registry).
+- **policy file** — `.safedeps.toml` 로 \"우리 팀 정책: KEV hit 자동 block, CVSS 7+ 사용자 컨펌, 특정 패키지 allowlist\" 명시.
+- **CI mode** — `safedeps check --ci` 로 GitHub Actions / CircleCI fail-fast.
+- **transitive risk score** — deps.dev graph 통합. 직접 dep 만 아니라 transitive dep 의 \"위험 점수\" 시각화.
+
+---
+
+## v4+ (장기)
+
+- **team-shared ledger** — multi-machine approved spec sync (회사 dev 모두가 같은 ledger 공유).
+- **AI agent integration** — Claude / Codex 가 vuln 발견 시 \"대체 모듈 X 권장\" 직접 제안 (LLM-as-judge).
+- **diff visualization UI** — 두 approved spec snapshot 사이의 dep tree diff 시각화.
+
+---
+
+## 명시적 NON-GOAL (이 도구는 하지 않는다)
+
+- **OS-level CVE 감시** (nginx, apt 패키지, system binary). → 별도 도구 `infra-cve-monitor` 결로 분리.
+- **컨테이너 이미지 스캔**. → Trivy / Grype.
+- **runtime 권한 sandbox**. → lavamoat / firejail.
+- **registry 자체의 손상 감지**. → registry 운영사 책임.
+- **사용자 평판 분석 (behavioral)**. → socket.dev.
+
+safedeps 의 결 = **\"개발 의존성 install 단계의 advisory + spec gate + rollback\"** 한 줄. 다른 결로 확장하지 않는다 — SRP 측면 다른 도구로 분리.
+
+---
+
+## 관련 미래 도구 (분리 권장)
+
+| 도구 | 결 | 관계 |
+|---|---|---|
+| `safedeps` (이것) | dev 의존성 (npm/pip/cargo/...) install 단계 | 현재 작업 |
+| `infra-cve-monitor` (가칭) | nginx / apt / OS package 주기적 audit + RSS 알람 | 미래 별 도구 |
+| `container-scan-bridge` (가칭) | Trivy / Grype wrapper, 컨테이너 이미지 결 | 미래 별 도구 |
+
+세 도구가 같은 결 (\"보안\") 의 다른 layer. 한 skill 에 통합하지 않고 분리.
+
+---
+
+## 변경 history
+
+- 2026-05-18: ROADMAP.md 최초 작성. v1 → v2 결정 + v3 / v4 / NON-GOAL 명시. (코덱시 surface:195 합의 + 클로디시 surface:61 작성.)