@aldegad/safedeps 2.1.1 → 2.2.0

package/SKILL.md

@@ -12,9 +12,11 @@ hooks:
 
 Safedeps protects development dependency installs with a three-phase flow:
 
-1. **Phase 1 — Advisory gate (`safedeps check`)**: query OSV (canonical advisory truth), CISA KEV (overlay), and GitHub Advisory (enrichment) before install. Write the approved (ecosystem, package, version) tuple to `~/.safedeps/approved-specs/<hash>.json` with a 30-day TTL.
-2. **Phase 2 — Hook enforcement (`scripts/safedeps-pre-guard.sh`)**: the PreToolUse hook does not call providers. It only checks the approved-spec ledger for the package/version in the about-to-run install command. Miss or expired → block with a structured message that names the exact `safedeps check` command to run next.
-3. **Phase 3 — Post-install reorg (`scripts/safedeps-post-verify.sh`)**: v1 reorg engine rolls back when the lockfile diverges from the approved spec or install scripts look suspicious.
+1. **Phase 1 — Advisory gate (`safedeps check`)**: query OSV (canonical advisory truth), CISA KEV (overlay), and GitHub Advisory (enrichment) before install. For npm, resolve the full dependency closure with a script-free lockfile probe and OSV `/v1/querybatch`; write the approved direct spec plus `transitive_specs` to `~/.safedeps/approved-specs/<hash>.json` with a 30-day TTL.
+2. **Phase 2 — Fast command guard (`scripts/safedeps-pre-guard.sh`)**: the PreToolUse hook does not call providers. It checks the approved-spec ledger for package/version tokens in the about-to-run install command and snapshots dependency truth. Miss or expired → block with a structured message that names the exact `safedeps check` command to run next. On Claude Code it also rewrites an npm install to add `--ignore-scripts` (hook `updatedInput`), so the install runs inert until verified; Codex CLI lacks `updatedInput`, so it falls back to detect-and-rollback.
+3. **Phase 3 — Effect enforcement + reorg (`scripts/safedeps-post-verify.sh`)**: PostToolUse is the primary enforcement surface for npm. It compares the actual `package-lock.json` closure against direct ledger entries and their `transitive_specs`, re-checks the closure with OSV batch, and rolls back when any package is unapproved/vulnerable or install scripts look suspicious. After a verified inert install it runs `npm rebuild` so the now-trusted lifecycle scripts execute.
+
+> **Release-time lane**: the `security-release-gates` orchestrator is absorbed into `safedeps gates`. It runs the repo-tree gates (secret scan, dependency audit, repo git-hook/CI check, install-guard presence) from one entry point, detecting and orchestrating the repo's `security:*` npm scripts, `scripts/security/*`, and gitleaks/npm-audit fallback. Splitting the individual `scan`/`audit`/`hooks`/`git` commands out and fully migrating a target repo's `scripts/security/*` is follow-up work. Design SSoT: [`ARCHITECTURE.md`](./ARCHITECTURE.md) §1 (Two Lanes).
 
 ## CLI Reference
 
@@ -24,6 +26,7 @@ safedeps ledger [--json]
 safedeps revoke <hash> | <ecosystem> <pkg>@<version> | <pkg>@<version> [--reason <r>] [--json]
 safedeps re-check [--json]
 safedeps migrate [--keep-legacy]
+safedeps gates [run] [--root <repo>] [--strict] [--no-run]
 safedeps help [command]
 safedeps version
 ```
@@ -55,6 +58,8 @@ You are the primary user of this skill when you propose `npm install`, `pip inst
 
    Use `--json` so the output is parseable. Read the `result` field.
 
+   If `safedeps` is not on your PATH, invoke it at the skill path instead — `~/.claude/skills/safedeps/bin/safedeps` (Claude Code) or `~/.codex/skills/safedeps/bin/safedeps` (Codex CLI). The hook's block messages already name a runnable path, so when blocked you never have to resolve this yourself.
+
 2. **Decide from `result`**:
 
    | `result` | Action |
@@ -64,7 +69,7 @@ You are the primary user of this skill when you propose `npm install`, `pip inst
    | `cve_unpatched` | Do **not** install. Surface the CVE list to the human, propose an alternative package. |
    | `kev_hard_block` | Do **not** install. Recommend an alternative module — the package is actively exploited in the wild. |
    | `provider_unavailable` | OSV is unreachable and there is no fresh cache. Do not install. Retry later or tell the human. |
-   | `error` | Argument parsing failed. Fix and retry. |
+   | `error` | Argument parsing or version/closure resolution failed (e.g. an unpublished version). Fix the spec and retry. |
 
 3. **Issue the install** only after the spec is approved. The hook re-checks the ledger; if the approved version differs from your install argument, the hook will block again — re-narrow and retry.
 
@@ -111,7 +116,7 @@ You are the primary user of this skill when you propose `npm install`, `pip inst
 }
 ```
 
-Both engines surface `permissionDecisionReason` back to you as the block message. Run the `safedeps check ...` command quoted inside backticks, parse the `--json` output, and retry the install with the approved version.
+Both engines surface `permissionDecisionReason` back to you as the block message. The command quoted inside backticks is already runnable as-is — bare `safedeps` when the CLI is on PATH, otherwise an absolute path. Run it **verbatim** (do not rewrite a full path back down to a bare `safedeps`), parse the `--json` output, and retry the install with the approved version.
 
 ### Hard rules
 
@@ -159,7 +164,8 @@ Disable color with `--no-color` or `NO_COLOR=1`. Non-TTY pipes also strip color
 - `lib/providers/providers.sh` — OSV / CISA KEV / GitHub Advisory adapters with a single query interface and 24h local cache under `~/.safedeps/cache/`.
 - `lib/ledger/ledger.sh` — approved spec JSON ledger I/O under `~/.safedeps/approved-specs/`, deterministic spec hash, TTL checks, atomic writes.
 - `scripts/safedeps-pre-guard.sh` — PreToolUse hook. v1 command pattern guard + ledger lookup for install commands.
-- `scripts/safedeps-post-verify.sh` — PostToolUse hook. v1 rollback engine + approved-spec diff.
+- `scripts/safedeps-post-verify.sh` — PostToolUse hook. v1 rollback engine + npm effect gate (lockfile closure vs ledger + OSV batch).
+- `lib/npm/closure.sh` — npm lockfile closure extraction and script-free temp lockfile resolver.
 - `scripts/install/install-safedeps-hooks.mjs` — cross-engine installer. Symlinks `~/.claude/skills/safedeps` and `~/.codex/skills/safedeps`, idempotently patches `~/.claude/settings.json` and `~/.codex/hooks.json`. `--uninstall` removes both.
 
 ## Provider Failure Policy
@@ -182,7 +188,7 @@ What it does:
 - Symlink the repo at `~/.claude/skills/safedeps` (when `~/.claude` exists) and `~/.codex/skills/safedeps` (when `~/.codex` exists).
 - Patch `~/.claude/settings.json` `hooks.PreToolUse[matcher=Bash]` and `hooks.PostToolUse[matcher=Bash]` with the canonical script paths.
 - Patch `~/.codex/hooks.json` with the same matcher and paths.
-- Optionally symlink `~/.local/bin/safedeps -> bin/safedeps` so the CLI is on PATH.
+- Optionally symlink `~/.local/bin/safedeps -> bin/safedeps` (via `--link-bin`) for a clean `safedeps` on PATH. **Not required** — the hook block messages and this skill fall back to the absolute skill-relative path, so the gate is fully self-contained without any PATH setup.
 
 Manual registration is also supported — see [Claude Code Hooks reference](https://code.claude.com/docs/en/hooks) and [Codex CLI Hooks](https://developers.openai.com/codex/hooks). The canonical script paths are:
 

package/bin/safedeps

@@ -7,7 +7,7 @@
 
 set -euo pipefail
 
-SAFEDEPS_VERSION="2.1.0"
+SAFEDEPS_VERSION="2.2.0"
 
 # ---- repo / lib bootstrap ----------------------------------------------------
 
@@ -18,6 +18,8 @@ SAFEDEPS_REPO_DIR=$(cd "${SAFEDEPS_BIN_DIR}/.." && pwd)
 source "${SAFEDEPS_REPO_DIR}/lib/providers/providers.sh"
 # shellcheck source=../lib/ledger/ledger.sh
 source "${SAFEDEPS_REPO_DIR}/lib/ledger/ledger.sh"
+# shellcheck source=../lib/npm/closure.sh
+source "${SAFEDEPS_REPO_DIR}/lib/npm/closure.sh"
 
 SAFEDEPS_HOME="${SAFEDEPS_HOME:-${HOME}/.safedeps}"
 SAFEDEPS_LEDGER_DIR="${SAFEDEPS_LEDGER_DIR:-${SAFEDEPS_HOME}/approved-specs}"
@@ -159,9 +161,10 @@ sf_resolve_version() {
   esac
 }
 
-# Extract lowest patched version greater than current_version from OSV vulns.
-# Echoes the patched version on stdout, or returns 1 if no usable fix.
-sf_extract_patched_version() {
+# Extract fixed version candidates greater than current_version from OSV vulns.
+# Echoes unique candidates in ascending version order, bounded for deterministic
+# provider retry behavior.
+sf_extract_patched_versions() {
   local provider_json_file="$1" current_version="$2"
   local fixed
   fixed=$(jq -r '
@@ -172,24 +175,14 @@ sf_extract_patched_version() {
 
   [[ -z "${fixed}" ]] && return 1
 
-  local candidate=""
   while IFS= read -r v; do
     [[ -z "${v}" ]] && continue
     # require v > current_version
     local higher
     higher=$(printf '%s\n%s\n' "${v}" "${current_version}" | sort -V | tail -1)
     [[ "${higher}" != "${v}" || "${v}" == "${current_version}" ]] && continue
-    if [[ -z "${candidate}" ]]; then
-      candidate="${v}"
-    else
-      local lower
-      lower=$(printf '%s\n%s\n' "${candidate}" "${v}" | sort -V | head -1)
-      candidate="${lower}"
-    fi
-  done <<< "${fixed}"
-
-  [[ -n "${candidate}" ]] || return 1
-  printf '%s' "${candidate}"
+    printf '%s\n' "${v}"
+  done <<< "${fixed}" | sort -Vu | head -20
 }
 
 sf_advisory_log() {
@@ -198,6 +191,21 @@ sf_advisory_log() {
   printf '[%s] %s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$*" >> "${SAFEDEPS_ADVISORY_LOG}"
 }
 
+sf_ledger_has_approval_provenance() {
+  local hash="$1"
+  local ecosystem="$2"
+  local package_name="$3"
+  local version="$4"
+
+  [[ -f "${SAFEDEPS_ADVISORY_LOG}" ]] || return 0
+  grep -F "check approve" "${SAFEDEPS_ADVISORY_LOG}" 2>/dev/null \
+    | grep -F "hash=${hash}" >/dev/null 2>&1 && return 0
+  grep -F "check approve" "${SAFEDEPS_ADVISORY_LOG}" 2>/dev/null \
+    | grep -F "ecosystem=${ecosystem}" \
+    | grep -F "package=${package_name}" \
+    | grep -F "version=${version}" >/dev/null 2>&1
+}
+
 # Emit either JSON or human text. Both forms describe the same event.
 sf_emit_json() {
   if [[ "${SAFEDEPS_JSON_MODE}" -eq 1 ]]; then
@@ -205,6 +213,267 @@ sf_emit_json() {
   fi
 }
 
+sf_closure_temp_file() {
+  local tmp_dir="${TMPDIR:-/tmp}"
+
+  mkdir -p "${tmp_dir}"
+  mktemp "${tmp_dir%/}/safedeps-closure.XXXXXX"
+}
+
+sf_npm_closure_for_spec() {
+  local package_name="$1"
+  local version="$2"
+  local closure_file="$3"
+
+  if ! safedeps_npm_resolve_spec_closure "${package_name}" "${version}" > "${closure_file}"; then
+    sf_eprintf "safedeps: npm closure resolution failed for ${package_name}@${version}"
+    return 1
+  fi
+
+  jq -e 'type == "array" and length > 0' "${closure_file}" >/dev/null || {
+    sf_eprintf "safedeps: npm closure is empty for ${package_name}@${version}"
+    return 1
+  }
+}
+
+sf_npm_batch_check_closure() {
+  local closure_file="$1"
+  local batch_file="$2"
+
+  if ! safedeps_providers_query_batch "npm" "${closure_file}" > "${batch_file}"; then
+    return 1
+  fi
+  jq -e 'type == "array"' "${batch_file}" >/dev/null
+}
+
+sf_npm_transitive_file_from_closure() {
+  local closure_file="$1"
+  local package_name="$2"
+  local version="$3"
+  local output_file="$4"
+
+  jq -c --arg package "${package_name}" --arg version "${version}" '
+    [
+      .[]
+      | select(.package != $package or (.version | tostring) != $version)
+      | {ecosystem: "npm", package: .package, version: (.version | tostring)}
+    ]
+    | unique_by(.ecosystem + "\u0000" + .package + "\u0000" + .version)
+    | sort_by(.package, .version)
+  ' "${closure_file}" > "${output_file}"
+}
+
+sf_npm_evidence_file() {
+  local provider_file="$1"
+  local closure_file="$2"
+  local output_file="$3"
+
+  jq -cn \
+    --slurpfile provider "${provider_file}" \
+    --slurpfile closure "${closure_file}" \
+    '{
+      closure_checked: true,
+      closure_checked_at: (now | todateiso8601),
+      provider: {type: "osv-querybatch", results: $provider[0]},
+      closure: $closure[0]
+    }' > "${output_file}"
+}
+
+sf_ledger_hit_has_npm_closure() {
+  local ledger_check="$1"
+
+  jq -e '.approved == true and (.spec.evidence.closure_checked == true)' <<< "${ledger_check}" >/dev/null 2>&1
+}
+
+sf_npm_emit_closure_block_json() {
+  local result="$1"
+  local ecosystem="$2"
+  local package_name="$3"
+  local range="$4"
+  local version="$5"
+  local batch_file="$6"
+
+  jq -c \
+    --arg result "${result}" \
+    --arg ecosystem "${ecosystem}" \
+    --arg package "${package_name}" \
+    --arg range "${range}" \
+    --arg version "${version}" \
+    '{
+      command:"check",
+      ecosystem:$ecosystem,
+      package:$package,
+      input_range:$range,
+      resolved_version:$version,
+      result:$result,
+      approved:false,
+      closure_vulnerabilities: [
+        .[]
+        | select((.status == "vulnerable") or (.status == "hard_block"))
+        | {
+            package: .package,
+            version: .version,
+            direct: (.direct // false),
+            result: .status,
+            vulnerabilities: (.vulnerabilities // []),
+            kev: (.kev // {})
+          }
+      ]
+    }' "${batch_file}"
+}
+
+sf_cmd_check_npm_full_closure() {
+  local ecosystem="$1"
+  local pkg="$2"
+  local range="$3"
+  local version="$4"
+  local closure_file
+  local batch_file
+  local evidence_file
+  local transitive_file
+  local direct_status
+  local vulnerable_count
+  local kev_count
+
+  closure_file=$(sf_closure_temp_file)
+  batch_file=$(sf_closure_temp_file)
+  evidence_file=$(sf_mktemp_evidence)
+  transitive_file=$(sf_closure_temp_file)
+
+  sf_spinner_start "npm closure 해석 중 (${pkg}@${version})"
+  if ! sf_npm_closure_for_spec "${pkg}" "${version}" "${closure_file}"; then
+    sf_spinner_stop
+    rm -f "${closure_file}" "${batch_file}" "${evidence_file}" "${transitive_file}"
+    if [[ "${SAFEDEPS_JSON_MODE}" -eq 1 ]]; then
+      jq -nc --arg ecosystem "${ecosystem}" --arg package "${pkg}" --arg range "${range}" --arg version "${version}" \
+        '{command:"check", ecosystem:$ecosystem, package:$package, input_range:$range, resolved_version:$version, result:"error", approved:false, error:"npm_closure_resolution_failed"}'
+    fi
+    return 4
+  fi
+  sf_spinner_stop
+
+  sf_spinner_start "closure 취약점 batch 조회 중 (OSV / KEV)"
+  if ! sf_npm_batch_check_closure "${closure_file}" "${batch_file}"; then
+    sf_spinner_stop
+    sf_err "OSV batch 응답 없음 — fail-closed (closure cache miss + 라이브 실패)"
+    sf_advisory_log "check fail-closed npm-closure package=${pkg} version=${version}"
+    rm -f "${closure_file}" "${batch_file}" "${evidence_file}" "${transitive_file}"
+    if [[ "${SAFEDEPS_JSON_MODE}" -eq 1 ]]; then
+      jq -nc \
+        --arg ecosystem "${ecosystem}" --arg package "${pkg}" \
+        --arg range "${range}" --arg version "${version}" \
+        '{command:"check", ecosystem:$ecosystem, package:$package, input_range:$range, resolved_version:$version, result:"provider_unavailable", approved:false, error:"OSV batch primary unavailable; no fresh cache for full closure"}'
+    fi
+    return 4
+  fi
+  sf_spinner_stop
+
+  vulnerable_count=$(jq '[.[] | select(.status == "vulnerable")] | length' "${batch_file}")
+  kev_count=$(jq '[.[] | select(.status == "hard_block")] | length' "${batch_file}")
+  direct_status=$(jq -r --arg package "${pkg}" --arg version "${version}" '
+    map(select(.package == $package and .version == $version)) | .[0].status // "missing"
+  ' "${batch_file}")
+
+  if [[ "${kev_count}" -gt 0 ]]; then
+    local kev_summary
+    kev_summary=$(jq -r '[.[] | select(.status == "hard_block") | "\(.package)@\(.version)" + (if .direct then " (direct)" else " (transitive)" end)] | join(", ")' "${batch_file}")
+    sf_err "KEV 매칭 closure 감지 — 설치 차단: ${kev_summary}"
+    sf_advisory_log "check block(KEV closure) package=${pkg} version=${version} affected=${kev_summary}"
+    if [[ "${SAFEDEPS_JSON_MODE}" -eq 1 ]]; then
+      sf_npm_emit_closure_block_json "kev_hard_block" "${ecosystem}" "${pkg}" "${range}" "${version}" "${batch_file}"
+    fi
+    rm -f "${closure_file}" "${batch_file}" "${evidence_file}" "${transitive_file}"
+    return 3
+  fi
+
+  if [[ "${vulnerable_count}" -gt 0 ]]; then
+    local block_result="closure_vulnerable"
+    if [[ "${direct_status}" == "vulnerable" ]]; then
+      local direct_json
+      local direct_evidence
+      local patched_versions=()
+      local patched_version
+      direct_evidence=$(sf_mktemp_evidence)
+      if safedeps_providers_query "${ecosystem}" "${pkg}" "${version}" > "${direct_evidence}"; then
+        while IFS= read -r patched_version; do
+          [[ -z "${patched_version}" ]] && continue
+          patched_versions+=("${patched_version}")
+        done < <(sf_extract_patched_versions "${direct_evidence}" "${version}" || true)
+      fi
+
+      for patched_version in "${patched_versions[@]+${patched_versions[@]}}"; do
+        sf_warn "${pkg}@${version} direct 취약 — 후보 ${patched_version} closure 재조회 중."
+        if ! sf_npm_closure_for_spec "${pkg}" "${patched_version}" "${closure_file}"; then
+          continue
+        fi
+        if ! sf_npm_batch_check_closure "${closure_file}" "${batch_file}"; then
+          rm -f "${direct_evidence}" "${closure_file}" "${batch_file}" "${evidence_file}" "${transitive_file}"
+          return 4
+        fi
+        vulnerable_count=$(jq '[.[] | select(.status == "vulnerable" or .status == "hard_block")] | length' "${batch_file}")
+        if [[ "${vulnerable_count}" -ne 0 ]]; then
+          continue
+        fi
+
+        sf_npm_transitive_file_from_closure "${closure_file}" "${pkg}" "${patched_version}" "${transitive_file}"
+        sf_npm_evidence_file "${batch_file}" "${closure_file}" "${evidence_file}"
+        local spec_json
+        spec_json=$(safedeps_ledger_write_approved_spec "${ecosystem}" "${pkg}" "${patched_version}" "${patched_version}" "safedeps-cli" "${evidence_file}" "${SAFEDEPS_LEDGER_DEFAULT_TTL_DAYS}" "${transitive_file}")
+        local hash; hash=$(jq -r '.hash' <<< "${spec_json}")
+        local expires_at; expires_at=$(jq -r '.expires_at' <<< "${spec_json}")
+        local transitive_count; transitive_count=$(jq 'length' "${transitive_file}")
+        sf_ok "${pkg}@${patched_version} full closure 승인 (transitive ${transitive_count}, until ${expires_at})"
+        sf_info "ledger: ${hash}"
+        sf_advisory_log "check approve(patched closure) package=${pkg} version=${patched_version} hash=${hash} transitive=${transitive_count} prev_version=${version}"
+        rm -f "${direct_evidence}" "${closure_file}" "${batch_file}" "${evidence_file}" "${transitive_file}"
+        if [[ "${SAFEDEPS_JSON_MODE}" -eq 1 ]]; then
+          jq -nc \
+            --arg ecosystem "${ecosystem}" --arg package "${pkg}" \
+            --arg range "${range}" --arg version "${version}" \
+            --arg patched "${patched_version}" \
+            --arg hash "${hash}" --arg expires_at "${expires_at}" \
+            --argjson transitive_count "${transitive_count}" \
+            '{command:"check", ecosystem:$ecosystem, package:$package, input_range:$range, resolved_version:$version, suggested_spec:$patched, result:"patched_available", approved:true, spec_hash:$hash, expires_at:$expires_at, transitive_count:$transitive_count, install_hint:("install with " + $package + "@" + $patched)}'
+        fi
+        return 0
+      done
+      block_result="cve_unpatched"
+      rm -f "${direct_evidence}"
+    fi
+
+    local affected_summary
+    affected_summary=$(jq -r '[.[] | select(.status == "vulnerable") | "\(.package)@\(.version)" + (if .direct then " (direct)" else " (transitive)" end)] | join(", ")' "${batch_file}")
+    sf_warn "closure 에 취약 패키지 감지 — 승인 보류: ${affected_summary}"
+    sf_advisory_log "check block(vulnerable closure) package=${pkg} version=${version} affected=${affected_summary}"
+    if [[ "${SAFEDEPS_JSON_MODE}" -eq 1 ]]; then
+      sf_npm_emit_closure_block_json "${block_result}" "${ecosystem}" "${pkg}" "${range}" "${version}" "${batch_file}"
+    fi
+    rm -f "${closure_file}" "${batch_file}" "${evidence_file}" "${transitive_file}"
+    return 2
+  fi
+
+  sf_npm_transitive_file_from_closure "${closure_file}" "${pkg}" "${version}" "${transitive_file}"
+  sf_npm_evidence_file "${batch_file}" "${closure_file}" "${evidence_file}"
+  local spec_json
+  spec_json=$(safedeps_ledger_write_approved_spec "${ecosystem}" "${pkg}" "${version}" "${range:-${version}}" "safedeps-cli" "${evidence_file}" "${SAFEDEPS_LEDGER_DEFAULT_TTL_DAYS}" "${transitive_file}")
+  local hash; hash=$(jq -r '.hash' <<< "${spec_json}")
+  local expires_at; expires_at=$(jq -r '.expires_at' <<< "${spec_json}")
+  local transitive_count; transitive_count=$(jq 'length' "${transitive_file}")
+  sf_ok "${pkg}@${version} full closure 승인 (transitive ${transitive_count}, until ${expires_at})"
+  sf_info "ledger: ${hash}"
+  sf_advisory_log "check approve(clean closure) package=${pkg} version=${version} hash=${hash} transitive=${transitive_count}"
+  rm -f "${closure_file}" "${batch_file}" "${evidence_file}" "${transitive_file}"
+  if [[ "${SAFEDEPS_JSON_MODE}" -eq 1 ]]; then
+    jq -nc \
+      --arg ecosystem "${ecosystem}" --arg package "${pkg}" \
+      --arg range "${range}" --arg version "${version}" \
+      --arg hash "${hash}" --arg expires_at "${expires_at}" \
+      --argjson transitive_count "${transitive_count}" \
+      '{command:"check", ecosystem:$ecosystem, package:$package, input_range:$range, resolved_version:$version, result:"clean", approved:true, spec_hash:$hash, expires_at:$expires_at, transitive_count:$transitive_count, install_hint:("install with " + $package + "@" + $version)}'
+  fi
+  return 0
+}
+
 # ---- check -------------------------------------------------------------------
 
 cmd_check() {
@@ -252,7 +521,7 @@ cmd_check() {
   # Ledger lookup short-circuit
   local ledger_check
   if ledger_check=$(safedeps_ledger_check "${ecosystem}" "${pkg}" "${version}" 2>/dev/null); then
-    if [[ "$(jq -r '.approved' <<< "${ledger_check}")" == "true" ]]; then
+    if [[ "$(jq -r '.approved' <<< "${ledger_check}")" == "true" ]] && { [[ "${ecosystem}" != "npm" ]] || sf_ledger_hit_has_npm_closure "${ledger_check}"; }; then
       local hash approved_at expires_at
       hash=$(jq -r '.hash' <<< "${ledger_check}")
       approved_at=$(jq -r '.spec.approved_at // "n/a"' <<< "${ledger_check}")
@@ -275,6 +544,11 @@ cmd_check() {
     fi
   fi
 
+  if [[ "${ecosystem}" == "npm" ]]; then
+    sf_cmd_check_npm_full_closure "${ecosystem}" "${pkg}" "${range}" "${version}"
+    return $?
+  fi
+
   # Provider query (canonical truth = OSV; KEV overlay; GHSA enrichment)
   local provider_json
   sf_spinner_start "취약점 조회 중 (OSV / KEV / GHSA)"
@@ -321,30 +595,45 @@ cmd_check() {
       ;;
 
     vulnerable)
-      local patched_version=""
-      if patched_version=$(sf_extract_patched_version "${tmp_evidence}" "${version}"); then
-        sf_warn "${pkg}@${version} 에 ${vuln_count} 개 CVE — 안전 버전 ${patched_version} 으로 좁혀 재조회합니다."
-        # narrow + recurse via providers (sub-call, no ledger short-circuit yet)
-        local narrow_json
-        sf_spinner_start "${patched_version} 재조회 중"
-        if ! narrow_json=$(safedeps_providers_query "${ecosystem}" "${pkg}" "${patched_version}"); then
+      local patched_versions=()
+      local patched_version
+      while IFS= read -r patched_version; do
+        [[ -z "${patched_version}" ]] && continue
+        patched_versions+=("${patched_version}")
+      done < <(sf_extract_patched_versions "${tmp_evidence}" "${version}" || true)
+
+      if [[ ${#patched_versions[@]} -gt 0 ]]; then
+        local narrow_json=""
+        local narrow_status=""
+        local last_patched=""
+        local last_status=""
+
+        for patched_version in "${patched_versions[@]}"; do
+          last_patched="${patched_version}"
+          sf_warn "${pkg}@${version} 에 ${vuln_count} 개 CVE — 후보 ${patched_version} 재조회 중."
+          sf_spinner_start "${patched_version} 재조회 중"
+          if ! narrow_json=$(safedeps_providers_query "${ecosystem}" "${pkg}" "${patched_version}"); then
+            sf_spinner_stop
+            sf_err "${pkg}@${patched_version} 재조회 실패 — fail-closed"
+            rm -f "${tmp_evidence}"
+            if [[ "${SAFEDEPS_JSON_MODE}" -eq 1 ]]; then
+              jq -nc \
+                --arg ecosystem "${ecosystem}" --arg package "${pkg}" \
+                --arg range "${range}" --arg version "${version}" \
+                --arg patched "${patched_version}" \
+                '{command:"check", ecosystem:$ecosystem, package:$package, input_range:$range, resolved_version:$version, suggested_spec:$patched, result:"provider_unavailable", approved:false}'
+            fi
+            return 4
+          fi
           sf_spinner_stop
-          sf_err "${pkg}@${patched_version} 재조회 실패 — fail-closed"
-          rm -f "${tmp_evidence}"
-          if [[ "${SAFEDEPS_JSON_MODE}" -eq 1 ]]; then
-            jq -nc \
-              --arg ecosystem "${ecosystem}" --arg package "${pkg}" \
-              --arg range "${range}" --arg version "${version}" \
-              --arg patched "${patched_version}" \
-              '{command:"check", ecosystem:$ecosystem, package:$package, input_range:$range, resolved_version:$version, suggested_spec:$patched, result:"provider_unavailable", approved:false}'
+
+          narrow_status=$(jq -r '.status' <<< "${narrow_json}")
+          last_status="${narrow_status}"
+          if [[ "${narrow_status}" != "clean" ]]; then
+            sf_warn "패치 후보 ${patched_version} 도 깨끗하지 않음 (status=${narrow_status}); 다음 후보를 확인합니다."
+            continue
           fi
-          return 4
-        fi
-        sf_spinner_stop
 
-        local narrow_status
-        narrow_status=$(jq -r '.status' <<< "${narrow_json}")
-        if [[ "${narrow_status}" == "clean" ]]; then
           # approve patched version
           local narrow_evidence
           narrow_evidence=$(sf_mktemp_evidence)
@@ -367,18 +656,18 @@ cmd_check() {
               '{command:"check", ecosystem:$ecosystem, package:$package, input_range:$range, resolved_version:$version, suggested_spec:$patched, result:"patched_available", approved:true, spec_hash:$hash, expires_at:$expires_at, install_hint:("install with " + $package + "@" + $patched)}'
           fi
           return 0
-        else
-          sf_err "패치 버전 ${patched_version} 도 깨끗하지 않음 (status=${narrow_status})"
-          rm -f "${tmp_evidence}"
-          if [[ "${SAFEDEPS_JSON_MODE}" -eq 1 ]]; then
-            jq -nc \
-              --arg ecosystem "${ecosystem}" --arg package "${pkg}" \
-              --arg range "${range}" --arg version "${version}" \
-              --arg patched "${patched_version}" --arg status "${narrow_status}" \
-              '{command:"check", ecosystem:$ecosystem, package:$package, input_range:$range, resolved_version:$version, suggested_spec:$patched, result:"patched_still_vulnerable", approved:false, patched_status:$status}'
-          fi
-          return 2
+        done
+
+        sf_err "패치 후보를 모두 재조회했지만 clean 후보가 없음 (last=${last_patched}, status=${last_status})"
+        rm -f "${tmp_evidence}"
+        if [[ "${SAFEDEPS_JSON_MODE}" -eq 1 ]]; then
+          jq -nc \
+            --arg ecosystem "${ecosystem}" --arg package "${pkg}" \
+            --arg range "${range}" --arg version "${version}" \
+            --arg patched "${last_patched}" --arg status "${last_status}" \
+            '{command:"check", ecosystem:$ecosystem, package:$package, input_range:$range, resolved_version:$version, suggested_spec:$patched, result:"patched_still_vulnerable", approved:false, patched_status:$status}'
         fi
+        return 2
       else
         sf_warn "${pkg}@${version} 에 ${vuln_count} 개 CVE — 사용 가능한 patch 없음. 승인 보류."
         sf_advisory_log "check warn(no-patch) ecosystem=${ecosystem} package=${pkg} version=${version} vulns=${vuln_count}"
@@ -609,15 +898,22 @@ cmd_recheck() {
   done < <(find "${SAFEDEPS_LEDGER_DIR}" -maxdepth 1 -name '*.json' -type f -print0 2>/dev/null)
 
   local checked=0 still_clean=0
-  local newly_vuln_arr='[]' kev_hit_arr='[]' revoked_arr='[]'
+  local newly_vuln_arr='[]' kev_hit_arr='[]' revoked_arr='[]' suspected_forgery_arr='[]'
 
   for f in "${entries[@]+${entries[@]}}"; do
-    local ecosystem pkg version revoked_at
+    local ecosystem pkg version revoked_at hash
     ecosystem=$(jq -r '.ecosystem' "${f}")
     pkg=$(jq -r '.package' "${f}")
     version=$(jq -r '.version' "${f}")
     revoked_at=$(jq -r '.revoked_at // ""' "${f}")
+    hash=$(jq -r '.hash // ""' "${f}")
     [[ -n "${revoked_at}" ]] && continue
+    if [[ -f "${SAFEDEPS_ADVISORY_LOG}" ]] && ! sf_ledger_has_approval_provenance "${hash}" "${ecosystem}" "${pkg}" "${version}"; then
+      sf_warn "  provenance 없음 — 위조 의심 flag (revoke 안 함)"
+      suspected_forgery_arr=$(jq -c \
+        --arg ecosystem "${ecosystem}" --arg package "${pkg}" --arg version "${version}" --arg hash "${hash}" \
+        '. + [{ecosystem:$ecosystem, package:$package, version:$version, hash:$hash, reason:"missing_advisory_log_approval"}]' <<< "${suspected_forgery_arr}")
+    fi
     checked=$(( checked + 1 ))
 
     sf_info "재검증 ${ecosystem} ${pkg}@${version}"
@@ -658,9 +954,10 @@ cmd_recheck() {
       --argjson newly_vulnerable "${newly_vuln_arr}" \
       --argjson kev_hit "${kev_hit_arr}" \
       --argjson revoked "${revoked_arr}" \
+      --argjson suspected_forgery "${suspected_forgery_arr}" \
       --argjson checked "${checked}" \
       --argjson still_clean "${still_clean}" \
-      '{command:"re-check", checked:$checked, still_clean:$still_clean, newly_vulnerable:$newly_vulnerable, kev_hit:$kev_hit, revoked:$revoked}'
+      '{command:"re-check", checked:$checked, still_clean:$still_clean, newly_vulnerable:$newly_vulnerable, kev_hit:$kev_hit, revoked:$revoked, suspected_forgery:$suspected_forgery}'
     return 0
   fi
 
@@ -668,8 +965,11 @@ cmd_recheck() {
   local nv kv
   nv=$(jq -r 'length' <<< "${newly_vuln_arr}")
   kv=$(jq -r 'length' <<< "${kev_hit_arr}")
+  local fg
+  fg=$(jq -r 'length' <<< "${suspected_forgery_arr}")
   [[ "${nv}" -gt 0 ]] && sf_warn "새 CVE 매치로 ${nv} 개 revoke"
   [[ "${kv}" -gt 0 ]] && sf_err  "KEV 매치로 ${kv} 개 revoke"
+  [[ "${fg}" -gt 0 ]] && sf_warn "approval provenance 없는 ledger entry ${fg} 개 flag"
 }
 
 # ---- migrate -----------------------------------------------------------------
@@ -702,6 +1002,31 @@ cmd_migrate() {
   fi
 }
 
+# ---- release-time gates (absorbed from security-release-gates) ---------------
+
+cmd_gates() {
+  local script="${SAFEDEPS_REPO_DIR}/scripts/release-gates.sh"
+  if [[ ! -f "${script}" ]]; then
+    sf_eprintf "safedeps: release-gates script not found: ${script}"
+    return 4
+  fi
+  # default subcommand is 'run'
+  if [[ "${1:-}" == "run" ]]; then shift; fi
+  exec bash "${script}" "$@"
+}
+
+cmd_scan() {
+  exec bash "${SAFEDEPS_REPO_DIR}/lib/gates/scan.sh" "$@"
+}
+
+cmd_audit() {
+  exec bash "${SAFEDEPS_REPO_DIR}/lib/gates/audit.sh" "$@"
+}
+
+cmd_hooks() {
+  exec bash "${SAFEDEPS_REPO_DIR}/lib/gates/hooks.sh" "$@"
+}
+
 # ---- help / version ----------------------------------------------------------
 
 cmd_version() {
@@ -771,6 +1096,10 @@ COMMANDS
   revoke <hash | pkg@version>               Revoke an approved spec.
   re-check                                  Re-query providers for all approved specs.
   migrate                                   Migrate legacy npm-reorg-guard state.
+  gates [run]                               Release-time repo gates: secret scan, dep audit, hook/CI check.
+  scan secrets [--repo|--worktree|--staged] Run gitleaks secret scan (repo profile aware).
+  audit [npm]                               Run npm lockfile audit.
+  hooks <install|check>                     Install/verify repo-local git hooks.
   help [command]                            Show help.
   version                                   Print version.
 
@@ -830,6 +1159,10 @@ main() {
     revoke)   cmd_revoke   "$@" ;;
     re-check|recheck) cmd_recheck "$@" ;;
     migrate)  cmd_migrate  "$@" ;;
+    gates)    cmd_gates    "$@" ;;
+    scan)     cmd_scan     "$@" ;;
+    audit)    cmd_audit    "$@" ;;
+    hooks)    cmd_hooks    "$@" ;;
     help)     cmd_help     "$@" ;;
     version)  cmd_version ;;
     *)