asc-notarization

macOS の公証

App Store 以外で配布する macOS アプリを公証する必要がある場合は、このスキルを使用します。

前提条件

• Xcode がインストールされ、コマンドラインツールが設定されていること。
• 認証が設定されていること（asc auth login または ASC_* 環境変数）。
• ローカルのキーチェーンに Developer ID Application 証明書があること。
• アプリの Xcode プロジェクトが macOS 向けにビルドされること。

事前確認：署名 ID の確認

アーカイブを作成する前に、有効な Developer ID Application ID があることを確認します。

security find-identity -v -p codesigning | grep "Developer ID Application"

ID が見つからない場合は、https://developer.apple.com/account/resources/certificates/add で作成してください（App Store Connect API では Developer ID 証明書を作成できません）。

信頼設定の確認

codesign または xcodebuild が「Invalid trust settings」または「errSecInternalComponent」で失敗する場合、証明書に証明書チェーンを壊すカスタム信頼設定の上書きがある可能性があります。

# Check for custom trust settings
security dump-trust-settings 2>&1 | grep -A1 "Developer ID"

これらのエラーだけでは、信頼設定の上書きが原因だとは断定できません。修復を提案する前に、該当する証明書を確認してください。信頼設定の変更には、その証明書に対する明示的な許可が必要です。診断のために信頼設定の上書きを削除したり、任意のアプリに再署名したりしないでください。

手順 1：アーカイブ

xcodebuild archive \
  -scheme "YourMacScheme" \
  -configuration Release \
  -archivePath /tmp/YourApp.xcarchive \
  -destination "generic/platform=macOS"

手順 2：Developer ID で書き出す

Developer ID 配布用の ExportOptions plist を作成します。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>developer-id</string>
    <key>signingStyle</key>
    <string>automatic</string>
    <key>teamID</key>
    <string>YOUR_TEAM_ID</string>
</dict>
</plist>

アーカイブを書き出します。

xcodebuild -exportArchive \
  -archivePath /tmp/YourApp.xcarchive \
  -exportPath /tmp/YourAppExport \
  -exportOptionsPlist ExportOptions.plist

これにより、Developer ID Application で署名され、安全なタイムスタンプが付与された .app バンドルが生成されます。

書き出したアプリを検証する

書き出したアプリの既存の署名とネストされたコードを検証し、署名の詳細を表示します。

codesign --verify --deep --strict --verbose=2 "/tmp/YourAppExport/YourApp.app" && \
  codesign --display --verbose=4 "/tmp/YourAppExport/YourApp.app" 2>&1

次の点を確認します。

• 検証コマンドが正常終了すること。署名の詳細を表示するだけでは、署名の有効性は検証されません。
• Authority チェーンが Developer ID Application → Developer ID Certification Authority → Apple Root CA の順であり、TeamIdentifier が想定どおりであること。
• Timestamp が存在すること。

検証に失敗した場合、または署名 ID が想定と異なる場合は、パッケージ化やアップロードに進まないでください。原因を診断し、意図したアプリを再ビルドするか再書き出ししてから、もう一度確認してください。これらの確認ではバンドルは変更されず、公証の受理を確認することもできません。

検証に --sign や --force を追加しないでください。Apple のコード署名に関するガイダンスでは、--deep による再帰的な検証と、ネストされたコードを強制的に再署名する --deep --force による署名を区別しています。

手順 3：公証用の ZIP を作成する

ditto -c -k --keepParent "/tmp/YourAppExport/YourApp.app" "/tmp/YourAppExport/YourApp.zip"

手順 4：公証に提出する

非同期で送信

asc notarization submit --file "/tmp/YourAppExport/YourApp.zip"

結果を待つ

asc notarization submit --file "/tmp/YourAppExport/YourApp.zip" --wait

カスタムポーリング

asc notarization submit --file "/tmp/YourAppExport/YourApp.zip" --wait --poll-interval 30s --timeout 1h

手順 5：結果を確認する

ステータス

asc notarization status --id "SUBMISSION_ID" --output table

開発者ログ（失敗時）

asc notarization log --id "SUBMISSION_ID"

ログ URL を取得して、問題の詳細を確認します。

curl -sL "LOG_URL" | python3 -m json.tool

過去の提出一覧

asc notarization list --output table
asc notarization list --limit 5 --output table

手順 6：チケットをステープルする（任意）

公証が成功したら、チケットをステープルしてアプリをオフラインでも動作するようにします。

xcrun stapler staple "/tmp/YourAppExport/YourApp.app"

DMG または PKG で配布する場合は、コンテナを作成した後にステープルします。

# Create DMG
hdiutil create -volname "YourApp" -srcfolder "/tmp/YourAppExport/YourApp.app" -ov -format UDZO "/tmp/YourApp.dmg"
xcrun stapler staple "/tmp/YourApp.dmg"

対応ファイル形式

形式	用途
.zip	最も簡単な方法。署名済みの .app バンドルを ZIP 化します
.dmg	ドラッグ＆ドロップでインストールするディスクイメージ
.pkg	インストーラーパッケージ（Developer ID Installer 証明書が必要です）

PKG の公証

.pkg ファイルを公証するには、Developer ID Installer 証明書が必要です（Developer ID Application とは別の証明書です）。この証明書タイプは App Store Connect API では利用できません。https://developer.apple.com/account/resources/certificates/add で作成してください。

パッケージに署名します。

productsign --sign "Developer ID Installer: YOUR NAME (TEAM_ID)" unsigned.pkg signed.pkg

次に提出します。

asc notarization submit --file signed.pkg --wait

トラブルシューティング

書き出し中に「Invalid trust settings」が表示される

カスタム信頼設定の上書きが原因の一つとして考えられます。事前確認に記載された読み取り専用の方法で確認し、該当する証明書を特定してから、信頼設定を変更する許可を得てください。

「The binary is not signed with a valid Developer ID certificate」

アプリが Development 証明書または App Store 証明書で署名されています。ExportOptions.plist で method: developer-id を指定して再書き出ししてください。

「署名にセキュアなタイムスタンプが含まれていません」

手動の codesign 呼び出しには --timestamp を追加するか、タイムスタンプが自動的に追加される xcodebuild -exportArchive を使用してください。

大容量ファイルのアップロードがタイムアウトする

アップロードのタイムアウト時間を延長します。

ASC_UPLOAD_TIMEOUT=5m asc notarization submit --file ./LargeApp.zip --wait

署名が正しく見えるのに公証で「Invalid」が返される

具体的な問題を確認するには、開発者ログを取得してください。

asc notarization log --id "SUBMISSION_ID"

よくある原因：署名されていないネストされたバイナリ、Hardened Runtime の不足、タイムスタンプのない埋め込みライブラリです。

注意事項

• asc notarization コマンドは Apple Notary API v2 を使用します。xcrun notarytool は使用しません。
• 認証には、他の asc コマンドと同じ API キーを使用します。
• ファイルはストリーミング方式で Apple の S3 バケットに直接アップロードされます（ファイル全体をバッファリングしません）。
• 5 GB を超えるファイルは、自動的にマルチパートアップロードが使用されます。
• フラグを確認するには、必ず --help を使用してください：asc notarization submit --help。