PassNinja

passninja

PassNinja REST API のコマンドラインインターフェイスです。 /v1/pass_templates、/v1/passes、/v1/webhooks をラップし、シェルから Apple Wallet および Google Wallet のパスを管理できます。

インストール

macOS / Linux（Homebrew）

brew tap flomio/passninja
brew install passninja

Windows（PowerShell）

irm https://github.com/flomio/passninja-cli/releases/latest/download/install.ps1 | iex

cmd.exe から実行する場合：

powershell -ExecutionPolicy Bypass -Command "irm https://github.com/flomio/passninja-cli/releases/latest/download/install.ps1 | iex"

スクリプトは CPU（amd64、arm64、または 386）を検出し、最新の GitHub リリースから対応する バイナリをダウンロードして SHA256 を検証したうえで、 %LOCALAPPDATA%\Programs\passninja\ に配置し、そのディレクトリをユーザーの PATH に追加します。管理者権限は不要です。再実行すると、その場でアップグレードされます。

特定のバージョンを指定するか、インストール先ディレクトリを変更できます。

$env:PASSNINJA_VERSION = 'v1.2.3'
$env:PASSNINJA_INSTALL_DIR = 'C:\tools\passninja'
irm https://github.com/flomio/passninja-cli/releases/latest/download/install.ps1 | iex

Windows（Scoop）

すでに Scoop をお使いの場合：

scoop bucket add flomio https://github.com/flomio/scoop-passninja
scoop install passninja

Claude Desktop（ワンクリック .mcpb インストール）

チャットでパスのワークフローを操作するには、PassNinja MCP サーバーを Claude Desktop にインストールします。

1. 最新リリースから passninja.mcpb をダウンロードします。

2. ファイルをダブルクリックします。Claude Desktop にインストールダイアログが表示され、サーバーが公開する 31 個のツール（パステンプレート、発行済みパス、ウェブフック、 スキャンイベントアプリケーション、リーダー）が示されます。

3. ダイアログで API キー と アカウント ID の入力を求められます。 https://www.passninja.com/settings → API key で確認してください。

4. Install をクリックして Claude Desktop を再起動し、Claude に次のように依頼します。

   passninja のパステンプレートを一覧表示し、それぞれにインストールされているパスの数を教えてください。

   [email protected] 向けに ptk_0x002 の新しいパスを発行してください。

同梱のバイナリには Apple Developer ID でコード署名し、公証を受けているため、 macOS Gatekeeper の警告なしで実行できます。同じ .mcpb が macOS （ユニバーサル）、Linux（amd64）、Windows（amd64）で動作します。

このサーバーは公式の MCP Registry にも io.github.flomio/passninja-cli として登録されているため、レジストリに対応する MCP クライアントから自動的に検出してインストールできます。

認証

passninja auth
# Pastes your API key and account ID; verifies by hitting /v1/pass_templates
# and saves credentials to ~/.passninja-auth.json (0600).

または、環境変数／フラグで認証情報を渡します。

export PASSNINJA_API_KEY=...        PASSNINJA_ACCOUNT_ID=aid_0x002
passninja --api-key=... --account-id=... pass-template list

フラグ > 環境変数 > ~/.passninja-auth.json > ~/.passninja.yaml > デフォルト値。

同じ優先順位が MCP サーバーにも適用されます。Claude Desktop やその他の MCP クライアントから 起動される passninja mcp は、環境変数から PASSNINJA_API_KEY / PASSNINJA_ACCOUNT_ID を読み込み、設定されていない場合は認証ファイルを使用します。

Stdio MCP サーバー

CLI は Model Context Protocol サーバーとしても機能します。上記の .mcpb インストールで Claude Desktop に設定されますが、 クライアントが次のコマンドを起動するよう設定すれば、任意の MCP クライアント（Cursor、Cline、Zed など）に 接続できます。

passninja mcp

ツールの一覧（snake_case の名前は CLI のサブコマンドに対応します）：

whoami
pass_template_{list, get, required_fields, reader_config, create, delete}
pass_{list, get, create, update, delete, raw, decrypt}
webhook_{list, get, create, delete, results}

各ツールの入力スキーマ、破壊的操作に関するヒントの注釈、詳細な説明により、 LLM は外部ドキュメントがなくても正しい使い方を自ら見つけられます。

コマンド

passninja auth                                       Save API credentials
passninja whoami                                     Show the active credential / account
passninja version

passninja pass-template list
passninja pass-template get <ptk_0x...>
passninja pass-template required-fields <ptk_0x...>
passninja pass-template reader-config <ptk_0x...>          # NFC reader config (merchant id, collector, EC keys)
passninja pass-template create --name --platform --style [config flags]   # enterprise only
passninja pass-template update <ptk_0x...> [--name --set --remap --show/--hide --require/--optional] [config flags] [--replace]   # enterprise only
passninja pass-template delete <ptk_0x...> [--yes]          # enterprise only
#   config flags (create + update): --constrain-device/-browser/-ip,
#   --disable-apple-sharing/-google-sharing, --auto-recharge --balance-trigger --top-up-target

passninja pass create <ptk_0x...> [--field k=v | --data @file.json | --data '<json>']
passninja pass list <ptk_0x...>
passninja pass get <ptk_0x...> <pass_id>
passninja pass raw <ptk_0x...> <pass_id>
passninja pass update <ptk_0x...> <pass_id> [--field k=v | --data ... | --replace]
passninja pass delete <ptk_0x...> <pass_id> [--yes]
passninja pass decrypt <ptk_0x...> [--payload <hex> | --payload-file <path> | <stdin>] [--platform apple]
#   Google Smart Tap is session-bound — use `reader serve` on the reader host

# Enterprise only:
passninja webhook create --name --url --event <type> [--event <type> ...] [--pass-template ptk_0x...]
passninja webhook list [--page --per-page --pass-template]
passninja webhook get <webhook_id>
passninja webhook delete <webhook_id> [--yes]
passninja webhook results <webhook_id> [--page --per-page]

# Scan event system (premium):
passninja application list
passninja application get <app_0x...>
passninja application create --name --pass-template ptk_0x... [--kind log|validate|forward]
                             [--rescan-window <seconds>] [--endpoint-url <https>] [--bearer-token <secret>]
                             [--timeout-ms <100-8000>] [--on-endpoint-error accept|reject] [--description]
passninja application update <app_0x...> [--name --description --kind --rescan-window --endpoint-url
                             --bearer-token --timeout-ms --on-endpoint-error --active/--inactive]
passninja application delete <app_0x...> [--yes]

passninja reader list
passninja reader get <reader_id>
passninja reader create --name --location --application app_0x... [--application ...]   # prints the token once
passninja reader update <reader_id> [--name --location --status active|revoked --application ...]
passninja reader rotate-token <reader_id> [--yes]
passninja reader delete <reader_id> [--yes]
passninja reader config <reader_id>                        # merged reader config across bound templates
passninja reader serve --token rdr_... [--pcsc [--pcsc-reader <name>] | --listen host:port]
                       [--platform apple|google] [--heartbeat 5m | --no-heartbeat]
                       [--serial --manufacturer --model --firmware --source]
                       [--on-accept '<cmd>'] [--on-reject '<cmd>']

出力形式

フラグ	モード
--json	整形された JSON
--plaintext	装飾なしのタブ区切り（awk へのパイプに便利）
デフォルト	枠線付き ASCII テーブル

~/.passninja.yaml でセッション全体のデフォルトを設定できます。

default_output: json    # one of: table | json | plaintext
base_url: https://api.passninja.com/v1

Webhook イベント

passninja-site が出力する CloudEvents 1.0 の type 分類：

イベントタイプ	発生条件
pn.pass.installed	発行済みパスをデバイスが初めてインストールしたとき
pn.pass.updated	PATCH/PUT によってパスのフィールドが変更されたとき
pn.pass.uninstalled	最後のデバイスがパスを削除したとき
pn.pass.scanned	リーダーがスキャンイベントを記録したとき（scanId、readerSerial、result を含む）

将来の利用に備えて予約済み：pn.pass.issued、pn.pass.deleted、 pn.pass_template.created、pn.pass_template.updated、 pn.pass_template.deleted。

リーダーホストの実行

クラウド接続型のリーダー（VTAP Cloud、Famoco Tap&Go）は、スキャンを自ら PassNinja に送信します。単純なリーダー（Reyax RYRR30D、ACS WalletMate、Elatec TWN4）は独自のクラウド接続を持たないため、reader serve がその役割を担います。リーダーが取得した値をスキャンイベントとして送信し、サーバーから返される LED／ビープ音の指示を適用します。

セットアップは 3 つの手順で、リーダーホストで実行するのは最後の手順だけです。

# 1. an application decides what a scan means for one pass template
passninja application create --name "Front gate" --kind validate \
  --pass-template ptk_0x216 --rescan-window 14400

# 2. a reader binds to it; the token is printed once — save it
passninja reader create --name "Front gate" --location "Gate 2" \
  --application app_0x1

# 3. on the reader host (a Raspberry Pi, a kiosk PC, …)
passninja reader serve --token rdr_... --pcsc         # attached PC/SC reader
my-reader-daemon | passninja reader serve --token rdr_...   # or any daemon

serve は、そのリーダー専用のベアラートークンで認証します。リーダーホストにアカウント API キーは不要であり、保持させるべきではありません。

タップ値は次の 3 つのソースのいずれかから受け取ります。

• --pcsc は、接続された PC/SC 非接触リーダー（ACS WalletMate／WalletMate II、Mini モジュールを含む）を直接制御します。別のデーモンは不要です。ホストがウォレットのフローを実行します。Apple のタップでは VAS 暗号文を取得し、Android のタップではタップ中にサーバーで Smart Tap セッションに事前署名します（コレクターキーが PassNinja の外に出ることはありません）。その後、セキュアチャネルをネゴシエートし、暗号化されたバンドルを取得します。どちらもサーバー側での復号のために送信されるため、ホストがキー素材を保持することはありません。初代 WalletMate は RF ポーリングが無効な状態で出荷されますが、ベンダーの CCID ドライバーがインストールされていれば、serve が自動的に有効化します。macOS/Linux ではネイティブ（cgo）ビルドが必要です。go install と Homebrew のビルドが該当します。
• stdin（1 行に 1 つの値）—任意のリーダーデーモンの出力をパイプで渡します。
• --listen 127.0.0.1:8080 — ドライバーが POST するループバック HTTP エンドポイントです。

stdin／HTTP では、取得した APDU の生データに見える値はサーバー側での復号に回され、それ以外は復号済みのパスシリアルとして扱われます。

各結果は stdout に 1 つの JSON オブジェクトとして出力されます。

{"scanId":"9f8e7d6c-…","result":"accepted","pass":{"passTemplate":"ptk_0x216","passId":"fee4a257185906b92a"},
 "readerInstructions":{"success":true,"led":"green","beep":true,"message":"Accepted"}}

物理 LED を制御するには、結果フックを使用してください。フックには $PN_RESULT、$PN_LED、$PN_MESSAGE、$PN_PASS、$PN_SCAN_ID が渡されます。また、フォワードアプリケーションが応答した場合は $PN_FORWARD_BODY（エンドポイントの JSON 応答）も渡されます。フォワードアプリケーションでは、$PN_MESSAGE にエンドポイントの message がそのまま入り、出力されるスキャン JSON には応答が forwardResponse の下に含まれます。

passninja reader serve --token rdr_... \
  --on-accept 'gpioset 0 17=1' --on-reject 'gpioset 0 27=1'

ハートビート（デフォルトでは 5 分ごと）は、稼働状況と、--serial／--manufacturer／--model／--firmware で渡したハードウェア ID を報告します。この情報がダッシュボードのリーダーのハードウェアパネルに表示されます。ベンダーの MDM ですでに管理されているリーダーでは、--no-heartbeat を使用してください。

passninja webhook create は作成時にベアラートークンを 一度だけ 返します。保存してください。再表示はできません。

ソースからのビルド

git clone https://github.com/flomio/passninja-cli.git
cd passninja-cli
make build                 # writes dist/passninja
./dist/passninja version
make install               # installs to $GOPATH/bin

リリースフロー

タグを起点とします。master に vX.Y.Z タグをプッシュすると、GitHub Actions ワークフロー .github/workflows/release.yml が darwin/linux × arm64/amd64 のマトリックスビルドを実行し、macOS ランナーでコード署名と Apple の公証を受けた passninja.mcpb をパッケージ化します。バイナリと .mcpb の両方を GitHub Release で公開し、flomio/homebrew-passninja に対して数式の url と sha256 を更新する PR を作成します。

Apple の認証情報はリポジトリシークレット（APPLE_TEAM_ID、APPLE_API_KEY_ID、APPLE_API_ISSUER_ID、APPLE_SIGN_IDENTITY、APPLE_CERTIFICATE_PASSWORD、および Base64 エンコードされた APPLE_API_KEY_P8 と APPLE_CERTIFICATE_P12）に保存されています。

タグ付きリリースのたびに、MCP Registry のエントリーを更新する必要があります。新しいリリースに合わせて、server.json の packages[0].identifier、packages[0].version、packages[0].fileSha256、およびトップレベルの version を更新し、次を実行してください。

mcp-publisher login github      # one-time per machine
mcp-publisher publish