jfrog-package-safety-and-download

JFrog パッケージの安全性とダウンロード

前提条件

• JFrog Platform の概念、ドメインモデル、CLI のセットアップ、API のパターンについては、../jfrog/SKILL.md を読んでください。
• OneModel のスキーマはサーバーのバージョンによって異なります。 GraphQL フィールドや where フィルターを新たに作成する前に、../jfrog/references/onemodel-graphql.md（スキーマの取得手順）と ../jfrog/references/onemodel-query-examples.md（Public packages、Stored packages）を読んでください。例が検証に失敗した場合は、GET "$JFROG_URL/onemodel/api/v1/supergraph/schema" を使用してクエリを再生成するか、検証してください。

ワークフローの概要

flowchart TD
    A[User requests package check / download] --> B{Package in Public Catalog?}
    B -->|Yes| C[Get latest version from Catalog]
    B -->|No| D{Package in JFrog Platform Stored Packages?}
    D -->|Yes| E[Get latest version from Stored Packages]
    D -->|No| F[Package not found — stop]
    C --> G{Latest version in JFrog Platform?}
    E --> G
    G -->|Yes| H[Safe — download from JFrog Platform]
    G -->|No| I{Curation entitled?}
    I -->|Yes| J[Check curation policy via API]
    I -->|No| K[Download via remote repo]
    J -->|200 Allowed| K
    J -->|403 Blocked| M[Report curation blocked — stop]

並列化の機会

このワークフローには、総レイテンシを短縮するために並列実行できる、互いに独立した手順がいくつかあります。

• 手順 1 + 手順 1 のフォールバック：パッケージの種類がわかっている場合は、Public Catalog（getPackage）と Stored Packages（getPackage）の両方に並列でクエリを実行します。データが返された方を使用します。Public Catalog で結果が見つかった場合は、手順 2 でその latestVersion を優先してください。
• 手順 3 + 手順 5：バージョンを特定した後、保存済みパッケージのバージョン（JFrog Platform の確認）とキュレーションの利用資格（/api/system/version）を並列でクエリします。どちらも独立した読み取り処理です。JFrog Platform の確認で結果が見つからなかった場合、キュレーションの結果がすぐに必要になります。

Shell 呼び出しを並列で実行する場合、各 jf api 呼び出しはアクティブな jf config サーバーに対して個別に認証されます。呼び出し間でシェルの状態を引き継ぐ必要はありません。

手順 1：パッケージを検索する

まず OneModel GraphQL を使用して Public Catalog を検索し、見つからない場合は Stored Packages を検索します。

../jfrog/references/onemodel-graphql.md の説明に従って jf api 経由でクエリを実行してください。具体的なクエリの形式については、../jfrog/references/onemodel-query-examples.md を参照してください。

パッケージの種類がわかっている場合（例：npm、maven、pypi）は、publicPackages.getPackage(type:, name:) を使用してください（Get a public package を参照）。latestVersion { version } の選択セットを含めてください。latestVersion はスカラーではなくオブジェクトです。

種類がわからない場合は、nameContains を指定して publicPackages.searchPackages を使用してください（Search public packages を参照）。ユーザーがエコシステムを絞り込んだ場合は、type: を追加してください。

• 見つかった場合 → type と latestVersion.version を記録します。手順 2 に進みます。
• 見つからない場合 → パッケージは 1st/2nd party の可能性があります。storedPackages.searchPackages または storedPackages.getPackage を使用して Stored Packages を検索してください（onemodel-query-examples.md の Stored packages domain を参照）。種類がわかっている場合は type でのフィルタリングを優先し、わからない場合は nameContains のみを使用してください。
  • 見つかった場合 → type と latestVersionName（または versionsConnection から取得したバージョン）を記録します。手順 2 に進みます。
  • どちらにも見つからない場合 →「パッケージが見つかりません」と報告して終了します。

type の値が異なる検索結果が複数ある場合は、どのパッケージの種類を指しているのかユーザーに確認してください。

手順 2：最新バージョンを特定する

ソース	バージョンフィールド
Public Catalog	latestVersion.version（オブジェクトの選択が必要）
JFrog Platform の Stored Packages	StoredPackage の latestVersionName、または versionsConnection の最も大きいバージョン

手順 3：パッケージと最新バージョンが JFrog Platform に存在するか確認する

hasPackageWith フィルターを指定して storedPackages.searchPackageVersions を使用し、保存済みパッケージのバージョンをクエリしてください（../jfrog/references/onemodel-query-examples.md → Search stored package versions を参照）。手順 2 で取得した特定のバージョンを指定する version フィルターを追加し、リポジトリの詳細（repositoryKey、repositoryType、leadArtifactPath）を取得するために locationsConnection をリクエストしてください。

jf api 経由でクエリを実行してください（呼び出し方法については ../jfrog/references/onemodel-graphql.md を参照）。

• ロケーションとともに見つかった場合 → パッケージは JFrog Platform にあります。ダウンロードしても安全と報告します。手順 4 に進みます。
• 見つからない場合 → 手順 5 に進みます。

ステップ 4：JFrog Platform からダウンロードする

ステップ 3 のロケーション情報を使用します。バイナリーアーティファクトのダウンロードには jf rt dl を使用します。jf api は使用しません。jf api は JFrog REST API（メタデータ、管理、キュレーションなど）の統一エントリーポイントであり、リダイレクトチェーンを介してバイナリーコンテンツをストリーミングするために必要な -L ／ -o フラグは公開していません。

<target> は完全なファイルパスである必要があります（例： ./downloads/lodash-4.18.1.tgz）。ディレクトリだけを指定してはいけません。jf rt dl --flat はターゲットをファイル名として扱うため、ディレクトリを渡すと、誤解を招く 「open path: is a directory」エラーが発生します。

repositoryType	戦略
local または federated	jf rt dl "<repositoryKey>/<leadArtifactPath>" <target-file> --flat
remote	ベースとなるリモートリポジトリに対して jf rt dl を実行します（末尾の -cache を削除）。アーティファクトがまだキャッシュされていない場合、透過的にリモートから取得します

local ／ federated ／ remote のダウンロード：

jf rt dl "<baseRepoKey>/<leadArtifactPath>" <target-file> --flat

リモートリポジトリキーの解決： OneModel が返すリモートロケーションの repositoryKey は、多くの場合、すでに末尾に -cache が付いています（例： devNPM-remote-cache）。jf rt dl には ベースとなるリモートリポジトリ名（-cache なし）が必要です。末尾に -cache がある場合は削除してください（例： devNPM-remote-cache → devNPM-remote）。キーの末尾が -cache でない場合は、そのまま使用します。

リポジトリ内のパッケージタイプ別のパス形式については、以下の プロトコルエンドポイント の表を参照してください。

ステップ 5：キュレーションの利用権を確認する

jf api /artifactory/api/system/version \
  | jq '.addons | index("curation") != null'

• true → キュレーションを利用できます。ステップ 6a に進みます。
• false → キュレーションを利用できません。ステップ 6b に進みます。

ステップ 6a：キュレーションポリシーを確認してダウンロードする

キュレーションを利用できる場合は、Xray キュレーション API を使用して、ダウンロード前にすべてのリポジトリでパッケージのバージョンが許可されているかを確認します。

RESPONSE_FILE="/tmp/curation-status-$$.json"
PAYLOAD_FILE="/tmp/curation-payload-$$.json"
STDERR_FILE="/tmp/curation-err-$$.log"

jq -n \
  --arg type    "<TYPE>"    \
  --arg name    "<NAME>"    \
  --arg version "<VERSION>" \
  '{packageType:$type, packageName:$name, packageVersion:$version}' \
  > "$PAYLOAD_FILE"

set +e
jf api /xray/api/v1/curation/package_status/all_repos \
  -X POST -H "Content-Type: application/json" \
  --input "$PAYLOAD_FILE" \
  > "$RESPONSE_FILE" 2> "$STDERR_FILE"
RC=$?
set -e
echo "RC=$RC"; echo "$RESPONSE_FILE"

サポートされている packageType の値：npm、pypi、maven、go、nuget、 docker、gradle。

jf api の結果の解釈： 通常の curl とは異なり、jf api は HTTP の結果を 終了コード と、標準エラー出力 に表示される "<hh:mm:ss> [Warn] ... returned 4xx/5xx" の行で示します（標準出力末尾の %{http_code} ではありません）。レスポンス本文は常に標準出力に書き込まれます。両方を解析してください。

if [ "$RC" -eq 0 ]; then
  echo "Package is allowed by curation."
elif grep -q 'returned 403' "$STDERR_FILE"; then
  echo "Blocked by curation policy:"
  cat "$RESPONSE_FILE"
else
  echo "Curation check failed (rc=$RC):"
  cat "$STDERR_FILE"
fi

結果を評価する：

• 終了コード 0 → パッケージはキュレーションポリシーによって 許可 されています。リモートリポジトリ経由でダウンロードします（ステップ 6b と同じ）。
• 標準エラー出力に returned 403 がある → パッケージはキュレーションポリシーによって ブロック されています。レスポンス本文に、どのポリシールールがブロックしたかが記載されています。ブロックの理由をユーザーに報告し、そこで終了します。ダウンロードを試みないでください。
• その他のゼロ以外の終了コード → 運用上の障害（認証、DNS、エンドポイントの無効化）として扱い、報告します。

ステップ 6b：キュレーションなしでダウンロードする

キュレーションを利用できず、パッケージが JFrog Platform にない場合は、リモートリポジトリ経由で直接ダウンロードします。

1. 適切なパッケージタイプの リモートリポジトリを見つけます。

   jf api \
     "/artifactory/api/repositories?type=remote&packageType=<TYPE>" \
     | jq '.[].key'
   

2. ダウンロード — -cache なしのベースとなるリモートリポジトリに対して jf rt dl を実行します。キャッシュ済みアーティファクトと未キャッシュのアーティファクトの両方を処理します。

   jf rt dl "<repo>/<artifact-path>" <target-file> --flat
   

パッケージタイプ別のアーティファクトパス

OneModel から leadArtifactPath を取得できない場合は、以下のパスパターンを使用します。先頭の <repo>/ は、jf rt dl に渡すベースリポジトリキーです。

タイプ	jf rt dl のターゲットパターン
npm	<repo>/<pkg>/-/<pkg>-<version>.tgz
pypi	<repo>/<pkg>/<version>/<pkg>-<version>.tar.gz
maven	<repo>/<group-path>/<artifact>/<version>/<artifact>-<version>.jar
go	<repo>/<module>/@v/<version>.zip

注意点

• バイナリのダウンロードとjf apiの違い：jf apiはREST API用であり、バイナリコンテンツには使用できません。バイナリペイロードへのリダイレクトを透過的にたどることはなく、-L／-oも使用できません。実際のアーティファクトのダウンロードには、必ず（-cacheのリポジトリではなく）ベースのリモートリポジトリに対してjf rt dlを使用してください。
• jf rt dlとキャッシュされていないリモート：jf rt dl "<remote>/<path>"を実行すると、<remote>-cache/<path>ではなくベースのリモートリポジトリを対象とし、リモートからの取得が透過的に行われ、アーティファクトがキャッシュされます。jf apiでプロキシに事前に問い合わせようとしないでください。
• jf rt dl --flatの出力先はファイルパスである必要があります：単一のアーティファクトをダウンロードする場合、ディレクトリではなく、完全な出力先のファイルパス（例：./downloads/lodash-4.18.1.tgz）を指定してください。CLIは出力先のパスをファイルとして開きます。ディレクトリを指定すると、内容のわかりにくい「open path: is a directory」エラーが発生し、失敗する前に4回再試行されます。leadArtifactPathからファイル名を特定してください（最後の/より後の部分を取得します）。
• パッケージタイプの判別：ユーザーがパッケージタイプを指定しない場合、名前だけで検索するとPublic Catalogから複数のタイプが返されることがあります。先にユーザーに確認し、タイプを特定してください。
• CuratorのエンドポイントはXray配下にあります：/xray/api/v1/curation/package_status/all_reposを使用してください（jf api経由）。/artifactoryを先頭に付けないでください。
• jf apiでのCuratorの結果の判別：200／403の判定は、jf apiの終了コードと、stderr上のreturned NNNという行によって行います。stdoutに追加される%{http_code}によるものではありません。stderrをファイルにリダイレクトし（2> "$STDERR_FILE"）、Step 6aに示すようにRCとgrep 'returned 403'を使って分岐してください。
• Curator APIのパッケージタイプの値：小文字で指定し、npm、pypi、maven、go、nuget、docker、gradleのいずれかと一致させる必要があります。それ以外の値を指定するとエラーが返されます。