Keychain & Security エキスパート スキル

Philosophy: 無党派的で、正確性を重視。このスキルは事実、検証済みパターン、Apple 公式ドキュメントのベストプラクティスを提供します。アーキテクチャ要件ではなく、iOS 13+ を最小デプロイメント対象として、iOS 17+ への最新推奨事項と iOS 26（ポスト量子化以降）への先読みガイダンスが含まれます。すべてのコードパターンは Apple ドキュメント、DTS エンジニアの投稿（Quinn "The Eskimo!"）、WWDC セッション、OWASP MASTG に基づいており、記憶に頼ることはありません。

このスキルが対象とするもの： Apple プラットフォーム上での keychain 操作、biometric 認証、CryptoKit 暗号化、credential ライフサイクル管理、証明書トラスト、コンプライアンスマッピングのレビュー、改善、実装のリファレンス。

このスキルが対象としないもの： ネットワーキングガイド、サーバーサイドセキュリティリファレンス、App Transport Security マニュアル。TLS 設定、サーバー証明書管理、バックエンド認証アーキテクチャはスコープ外です。クライアント側の keychain や trust API に直接関わる場合を除きます。

---

目次

• Decision Tree
• Domain Selection Guide
• Agent Behavioral Rules
• Common Mistakes
• Top-Level Review Checklist
• Version Reference Table
• Self-Review Gate

Decision Tree

ユーザーの意図を把握し、該当するブランチに従います。曖昧な場合は確認してください。

                        ┌─────────────────────┐
                        │  What is the task?   │
                        └─────────┬───────────┘
               ┌──────────────────┼──────────────────┐
               ▼                  ▼                  ▼
          ┌─────────┐      ┌───────────┐      ┌────────────┐
          │ REVIEW  │      │  IMPROVE  │      │ IMPLEMENT  │
          │         │      │           │      │            │
          │ Audit   │      │ Migrate / │      │ Build from │
          │ existing│      │ modernize │      │ scratch    │
          │ code    │      │ existing  │      │            │
          └────┬────┘      └─────┬─────┘      └─────┬──────┘
               │                 │                   │
               ▼                 ▼                   ▼
        Run Top-Level      Identify gap         Identify which
        Review Checklist   (legacy store?        domain(s) apply,
        (§ below) against  wrong API?            load reference
        the code.          missing auth?)        file(s), follow
        Flag each item     Load migration +      ✅ patterns.
        as ✅ / ❌ /       domain-specific       Implement with
        ⚠️ N/A.           reference files.      add-or-update,
        For each ❌,       Follow ✅ patterns,   proper error
        cite the           verify with domain    handling, and
        reference file     checklist.            correct access
        and specific                             control from
        section.                                 the start.

---

Branch 1 — REVIEW（既存コードの監査）

目的： Keychain/セキュリティコードの正確性、セキュリティ、コンプライアンスを体系的に評価します。

手順：

1. Top-Level Review Checklist（以下）を実行 してレビュー対象コードに対して各項目を ✅ / ❌ / ⚠️ N/A でスコアリングします。
2. **各 ❌ 失敗について、**引用されたリファレンスファイルをロードして、特定のアンチパターンまたは正しいパターンを探します。
3. アンチパターンをクロスチェック — common-anti-patterns.md の 10 項目すべてに対してコードをスキャンします。特に注意してください：UserDefaults でのシークレット（#1）、ハードコードされたキー（#2）、LAContext.evaluatePolicy() のみの認証ゲート（#3）、無視された OSStatus（#4）。
4. コンプライアンス確認 — プロジェクトが OWASP MASVS またはエンタープライズ監査対応が必要な場合、compliance-owasp-mapping.md カテゴリ M1、M3、M9、M10 に調査結果をマッピングします。
5. レポート形式： 各検出事項について：何が問題か → どのリファレンスファイルがカバーするか → ✅ 正しいパターン → 重要度（CRITICAL / HIGH / MEDIUM）を記載します。

レビューの主要リファレンスファイル：

• 最初に：common-anti-patterns.md（バックボーン — 最も危険な 10 パターンをカバー）
• 次にコードが何をするかに基づくドメイン固有ファイル
• 最後に：compliance-owasp-mapping.md（コンプライアンスが関連する場合）

---

Branch 2 — IMPROVE（マイグレーション/モダナイゼーション）

目的： 不安全な保存、非推奨 API、または従来のパターンから現在のベストプラクティスへコードをアップグレードします。

手順：

1. マイグレーションの種類を特定します：

   • 不安全な保存 → Keychain：migration-legacy-stores.md + credential-storage-patterns.md をロード
   • 従来の Security framework → CryptoKit：cryptokit-symmetric.md または cryptokit-public-key.md + migration-legacy-stores.md をロード
   • RSA → 楕円曲線：cryptokit-public-key.md（RSA マイグレーションセクション）をロード
   • GenericPassword → InternetPassword（AutoFill）：keychain-item-classes.md（マイグレーションセクション）をロード
   • LAContext のみ → Keychain バインド biometrics：biometric-authentication.md をロード
   • ファイルベース keychain → データ保護 keychain（macOS）：keychain-fundamentals.md（TN3137 セクション）をロード
   • シングルアプリ → 共有 keychain（拡張機能）：keychain-sharing.md をロード
   • Leaf pinning → SPKI/CA pinning：certificate-trust.md をロード

2. 関連リファレンスファイルのマイグレーションパターンに従います。 すべてのマイグレーションセクションに含まれます：マイグレーション前の検証、アトミックマイグレーションステップ、レガシーデータの安全な削除、マイグレーション後の検証。

3. マイグレーション完了後、リファレンスファイルのドメイン固有チェックリストを実行します。

4. testing-security-code.md のガイダンスを使用してリグレッションがないことを確認します。

---

Branch 3 — IMPLEMENT（ゼロから構築）

目的： 新しい keychain/セキュリティ機能を最初から正しく構築します。

手順：

1. タスクが関わるドメイン（複数可）を特定します。 下記の Domain Selection Guide を使用します。
2. 関連リファレンスファイル（複数可）をロードします。 ✅ コードパターンに従います — コアセキュリティロジックについてそこから逸脱しません。
3. 以下の Core Guidelines をすべての実装に適用します。
4. 実装完了と見なす前に、ドメイン固有チェックリストを実行します。
5. testing-security-code.md に従ってテストを追加します — ユニットテスト用プロトコルベースの抽象化、デバイス上のインテグレーションテスト用の実際の keychain。

Domain Selection Guide：

タスクが関わる場合…	これらのリファレンスファイルをロード
パスワードまたはトークンの保存/読み取り	keychain-fundamentals.md + credential-storage-patterns.md
使用する kSecClass の選択	keychain-item-classes.md
アイテムがアクセス可能なときを設定	keychain-access-control.md
Face ID / Touch ID ゲーティング	biometric-authentication.md + keychain-access-control.md
ハードウェアバックキー	secure-enclave.md
データの暗号化/ハッシング	cryptokit-symmetric.md
署名/キー交換/HPKE	cryptokit-public-key.md
OAuth トークン/API キー/ログアウト	credential-storage-patterns.md
アプリと拡張機能間での共有	keychain-sharing.md
TLS pinning/クライアント証明書	certificate-trust.md
UserDefaults/plist シークレットの置換	migration-legacy-stores.md
セキュリティコードのテスト作成	testing-security-code.md
エンタープライズ監査/OWASP コンプライアンス	compliance-owasp-mapping.md

---

Core Guidelines

これら 7 つのルールは譲歩の余地がありません。すべての keychain/セキュリティ実装がこれらを満たす必要があります。

1. OSStatus を決して無視しない。 すべての SecItem* 呼び出しは OSStatus を返します。少なくとも以下をカバーする詳細な switch を使用します：errSecSuccess、errSecDuplicateItem（-25299）、errSecItemNotFound（-25300）、errSecInteractionNotAllowed（-25308）。戻り値を黙って破棄することは、ほとんどの keychain バグの根本原因です。→ keychain-fundamentals.md

2. LAContext.evaluatePolicy() をスタンドアロン認証ゲートとして決して使用しない。 これは Bool を返しますが、Frida による実行時パッチが容易です。Biometric 認証は keychain にバインドされている必要があります：SecAccessControl に .biometryCurrentSet を持つシークレットを保存し、SecItemCopyMatching 中に Face ID/Touch ID の keychain プロンプトを許可します。keychain はセキュアエンクレーブで認証を処理します。パッチするための Bool がありません。→ biometric-authentication.md

3. UserDefaults、Info.plist、.xcconfig、または NSCoding アーカイブにシークレットを決して保存しない。 これらは暗号化されていないバックアップから読み取り可能なプレーンテキストアーティファクトを生成します。Keychain が credentials の唯一の Apple 公式ストアです。→ credential-storage-patterns.md、common-anti-patterns.md

4. @MainActor で SecItem* を決して呼び出さない。 すべての keychain 呼び出しは securityd への IPC ラウンドトリップで、呼び出しスレッドをブロックします。すべての keychain アクセスに専用の actor（iOS 17+）または serial DispatchQueue（iOS 13–16）を使用します。→ keychain-fundamentals.md

5. 常に kSecAttrAccessible を明示的に設定する。 システムデフォルト（kSecAttrAccessibleWhenUnlocked）はすべてのバックグラウンド操作を破壊し、脅威モデルと一致しない可能性があります。アクセスパターンを満たす最も制限的なクラスを選択します。バックグラウンドタスク用：kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly。最高感度用：kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly。→ keychain-access-control.md

6. 常に add-or-update パターンを使用する。 SecItemAdd の後、errSecDuplicateItem で SecItemUpdate。delete-then-add は決して使用しない（レース窓を作成し、永続参照を破壊します）。errSecDuplicateItem ケースを処理しないで SecItemAdd を呼び出さない。→ keychain-fundamentals.md

7. 常に macOS でデータ保護 keychain をターゲットにする。 macOS ターゲットの SecItem* 呼び出しごとに kSecUseDataProtectionKeychain: true を設定します。これなしでは、クエリは従来のファイルベース keychain にサイレントにルーティングされます。これは異なる動作、サポートされていない属性の無視、biometric 保護またはセキュアエンクレーブキーの使用ができません。Mac Catalyst と iOS-on-Mac はこれを自動的に行います。→ keychain-fundamentals.md

---

クイックリファレンステーブル

Accessibility Constants — Selection Guide

定数	いつ復号化可能	バックアップ継続	デバイスマイグレーション継続	バックグラウンド安全	使用場面
WhenPasscodeSetThisDeviceOnly	ロック解除 + パスコード設定	❌	❌	❌	最高レベルのセキュリティシークレット；パスコード削除時に削除
WhenUnlockedThisDeviceOnly	ロック解除	❌	❌	❌	バックグラウンド不要のデバイスバウンドシークレット
WhenUnlocked	ロック解除	✅	✅	❌	同期可能なシークレット（システムデフォルト — 暗黙的使用を避ける）
AfterFirstUnlockThisDeviceOnly	最初のロック解除 → 再起動	❌	❌	✅	バックグラウンドタスク、プッシュハンドラー、デバイスバウンド
AfterFirstUnlock	最初のロック解除 → 再起動	✅	✅	✅	復元を継続するバックグラウンドタスク

非推奨（決して使用しない）： kSecAttrAccessibleAlways、kSecAttrAccessibleAlwaysThisDeviceOnly — iOS 12 で非推奨。

経験則： バックグラウンドアクセス必要（プッシュハンドラー、バックグラウンドリフレッシュ）？ AfterFirstUnlockThisDeviceOnly から開始。フォアグラウンド限定？ WhenUnlockedThisDeviceOnly から開始。高価値シークレットには WhenPasscodeSetThisDeviceOnly に厳格化。iCloud 同期またはバックアップマイグレーション必要な場合のみ非ThisDeviceOnly バリアントを使用。

CryptoKit Algorithm Selection

必要なもの	アルゴリズム	最小 iOS	注記
データをハッシュ	SHA256 / SHA384 / SHA512	13	SHA3_256/SHA3_512 は iOS 26+ で利用可能
データを認証（MAC）	HMAC<SHA256>	13	常に定時間比較で検証（組み込み）
データを暗号化（認証済み）	AES.GCM	13	256 ビットキー、96 ビットノンス、128 ビットタグ。同じキーでノンスを再利用しない
データを暗号化（モバイル最適化）	ChaChaPoly	13	AES-NI なしのデバイスでより良い（古い Apple Watch）
データに署名	P256.Signing / Curve25519.Signing	13	相互運用に P256 を使用、パフォーマンスに Curve25519 を使用
キー合意	P256.KeyAgreement / Curve25519.KeyAgreement	13	常に HKDF で対称キーを導出 — ロー共有シークレットを決して使用しない
ハイブリッド公開鍵暗号	HPKE	17	手動 ECDH+HKDF+AES-GCM チェーンを置換
ハードウェアバック署名	SecureEnclave.P256.Signing	13	P256 のみ；キーはハードウェアを離れません
ポスト量子キー交換	MLKEM768	26	形式検証（ML-KEM FIPS 203）
ポスト量子署名	MLDSA65	26	形式検証（ML-DSA FIPS 204）
パスワード → キー導出	PBKDF2（CommonCrypto 経由）	13	≥ 600,000 イテレーション SHA-256（OWASP 2024）
キー → キー導出	HKDF<SHA256>	13	Extract-then-expand；常にドメイン分離の info パラメータを使用

Anti-Pattern Detection — Quick Scan

コードレビュー時、これらのパターンを検索します。一致はすべて検出事項です。 ❌ = ユーザーコードで検出するインセキュアなパターン署名。✅ = 参照ファイルで応用する是正パターン。

検索対象	アンチパターン	重要度	リファレンス
UserDefaults.standard.set + token/key/secret/password	プレーンテキスト credentials 保存	CRITICAL	common-anti-patterns.md #1
ソース内でハードコードされた base64/hex 文字列（≥16 文字）	ハードコードされた暗号キー	CRITICAL	common-anti-patterns.md #2
近くに SecItemCopyMatching がない evaluatePolicy	LAContext のみ biometric ゲート	CRITICAL	common-anti-patterns.md #3
戻り値/OSStatus をチェックしない SecItemAdd	無視されたエラーコード	HIGH	common-anti-patterns.md #4
add ディクショナリに kSecAttrAccessible がない	暗黙的な accessibility クラス	HIGH	common-anti-patterns.md #5
同じキーでループ内の AES.GCM.Nonce()	潜在的なノンス再利用	CRITICAL	common-anti-patterns.md #6
HKDF なしの sharedSecret.withUnsafeBytes	ロー共有シークレット as キー	HIGH	common-anti-patterns.md #7
kSecAttrAccessibleAlways	非推奨 accessibility	HIGH	keychain-access-control.md
#if !targetEnvironment(simulator) なしの SecureEnclave.isAvailable	シミュレータ偽陰性トラップ	MEDIUM	secure-enclave.md
kSecAttrSynchronizable: true + ThisDeviceOnly	矛盾した制約	MEDIUM	keychain-item-classes.md
SecTrustEvaluate（同期、非推奨）	レガシートラスト評価	MEDIUM	certificate-trust.md
kSecClassGenericPassword + kSecAttrServer	Web credentials の間違ったクラス	MEDIUM	keychain-item-classes.md

---

Top-Level Review Checklist

14 ドメインすべてにわたる高速スイープにこのチェックリストを使用します。各項目は 1 つ以上のリファレンスファイルにマップされ、詳細調査のためのものです。ドメイン固有の詳細チェックについては、各リファレンスファイルの下部にある Summary Checklist を使用します。

• 1. Secrets は Keychain にあり、UserDefaults/plist/ソースにはない — UserDefaults、Info.plist、.xcconfig、ハードコードされた文字列、または NSCoding アーカイブに credentials、トークン、または暗号化キーがない。OWASP M9（Insecure Data Storage）直接違反。→ common-anti-patterns.md #1–2、credential-storage-patterns.md、migration-legacy-stores.md、compliance-owasp-mapping.md

• 2. すべての OSStatus がチェックされている — すべての SecItem* 呼び出しが詳細な switch または同等のもので戻りコードを処理。無視された戻り値なし。errSecInteractionNotAllowed は非破壊的に処理（後で再試行、削除しない）。→ keychain-fundamentals.md、common-anti-patterns.md #4

• 3. Biometric 認証は keychain にバインドされている — Biometrics を使用する場合、認証は LAContext.evaluatePolicy() のみではなく SecAccessControl + keychain アクセスで実施。→ biometric-authentication.md、common-anti-patterns.md #3

• 4. Accessibility クラスは明示的かつ正確 — すべての keychain アイテムは、アクセスパターン（バックグラウンド vs フォアグラウンド、デバイスバウンド vs 同期可能）に一致する明示的な kSecAttrAccessible 値を持つ。非推奨の Always 定数なし。→ keychain-access-control.md

• 5. @MainActor での SecItem* 呼び出しなし — すべての keychain 操作は専用 actor またはバックグラウンドキューで実行。UI コード、viewDidLoad、または application(_:didFinishLaunchingWithOptions:) での同期 keychain アクセスなし。→ keychain-fundamentals.md

• 6. 各アイテムタイプに対する正しい kSecClass — Web credentials は AutoFill 用に InternetPassword（GenericPassword ではなく）を使用。暗号化キーは適切な kSecAttrKeyType を持つ kSecClassKey を使用。アプリシークレットは kSecAttrService + kSecAttrAccount を持つ GenericPassword を使用。→ keychain-item-classes.md

• 7. CryptoKit は正しく使用 — ノンスは同じキーで再利用されない。ECDH 共有シークレットは常に対称キーとして使用する前に HKDF で導出。SymmetricKey マテリアルは Keychain に保存、メモリやファイルに保存されない。Crypto 操作はプロトコルベースのユニットテストでカバー。→ cryptokit-symmetric.md、cryptokit-public-key.md、testing-security-code.md

• 8. Secure Enclave 制約は尊重 — SE キーは P256 のみ（古典的）、決してインポートされない（常にオンデバイスで生成）、デバイスバウンド（バックアップ/同期なし）。利用可能性チェックはシミュレータと keychain-access-groups 要件の問題から保護。→ secure-enclave.md

• 9. 共有とアクセスグループは正しく設定 — kSecAttrAccessGroup は完全な TEAMID.group.identifier 形式を使用。要件はアプリと拡張機能間で一致。偶発的なクロスアプリデータ公開なし。→ keychain-sharing.md

• 10. 証明書トラスト評価は最新 — SecTrustEvaluateAsyncWithError を使用（非推奨の同期 SecTrustEvaluate ではなく）。Pinning 戦略は SPKI ハッシュまたは NSPinnedDomains を使用（annual ローテーション破損の leaf 証明書 pinning ではなく）。→ certificate-trust.md

• 11. macOS ターゲットはデータ保護 keychain — すべての macOS SecItem* 呼び出しは kSecUseDataProtectionKeychain: true を含む（Mac Catalyst / iOS-on-Mac を除く、自動）。→ keychain-fundamentals.md

---

References Index

#	ファイル	ワンライン説明	リスク
1	keychain-fundamentals.md	SecItem* CRUD、クエリディクショナリ、OSStatus 処理、actor ベースのラッパー、macOS TN3137 ルーティング	CRITICAL
2	keychain-item-classes.md	5 つの kSecClass タイプ、複合主キー、GenericPassword vs InternetPassword、ApplicationTag vs ApplicationLabel	HIGH
3	keychain-access-control.md	7 つの accessibility 定数、SecAccessControl フラグ、データ保護層、NSFileProtection サイドバー	CRITICAL
4	biometric-authentication.md	Keychain バインド biometrics、LAContext バイパス脆弱性、登録変更検出、フォールバックチェーン	CRITICAL
5	secure-enclave.md	ハードウェアバック P256 キー、CryptoKit SecureEnclave モジュール、永続性、シミュレータトラップ、iOS 26 ポスト量子	HIGH
6	cryptokit-symmetric.md	SHA-2/3 ハッシング、HMAC、AES-GCM/ChaChaPoly 暗号化、SymmetricKey 管理、ノンス処理、HKDF/PBKDF2	HIGH
7	cryptokit-public-key.md	ECDSA 署名、ECDH キー合意、HPKE（iOS 17+）、ML-KEM/ML-DSA ポスト量子（iOS 26+）、曲線選択	HIGH
8	credential-storage-patterns.md	OAuth2/OIDC トークンライフサイクル、API キー保存、リフレッシュトークン回転、ランタイムシークレット、ログアウトクリーンアップ	CRITICAL
9	keychain-sharing.md	アクセスグループ、Team ID プレフィックス、アプリ拡張機能、Keychain Sharing vs App Groups 要件、iCloud 同期	MEDIUM
10	certificate-trust.md	SecTrust 評価、SPKI/CA/leaf pinning、NSPinnedDomains、クライアント証明書（mTLS）、信頼ポリシー	HIGH
11	migration-legacy-stores.md	UserDefaults/plist/NSCoding → Keychain マイグレーション、安全な削除、初回起動クリーンアップ、バージョン管理マイグレーション	MEDIUM
12	common-anti-patterns.md	トップ 10 AI 生成セキュリティミスと ❌/✅ コードペア、検出ヒューリスティック、OWASP マッピング	CRITICAL
13	testing-security-code.md	プロトコルベースモッキング、シミュレータ vs デバイス差異、CI/CD keychain、Swift Testing、ミューテーションテスト	MEDIUM
14	compliance-owasp-mapping.md	OWASP Mobile Top 10（2024）、MASVS v2.1.0、MASTG テスト ID、M1/M3/M9/M10 マッピング、監査準備	MEDIUM

---

Authoritative Sources

これらは、すべてのリファレンスファイルの基礎となる主要なソースです。疑わしい場合は、二次ソースより優先します。

• Apple Keychain Services Documentation — 正規 API リファレンス
• Apple Platform Security Guide（毎年更新） — アーキテクチャと暗号化設計
• TN3137: "On Mac Keychain APIs and Implementations" — macOS データ保護 vs ファイルベース keychain
• Quinn "The Eskimo!" DTS Posts — "SecItem: Fundamentals" と "SecItem: Pitfalls and Best Practices"（2025 年まで更新）
• WWDC 2019 Session 709 — "Cryptography and Your Apps"（CryptoKit 導入）
• WWDC 2025 Session 314 — "Get ahead with quantum-secure cryptography"（ML-KEM、ML-DSA）
• OWASP Mobile Top 10（2024） + MASVS v2.1.0 + MASTG v2 — コンプライアンスフレームワーク
• CISA/FBI "Product Security Bad Practices" v2.0（2025 年 1 月） — ハードコード credentials を国家セキュリティリスクに分類

---

Agent Behavioral Rules

以下のセクションは、このスキルを使用するときに AI エージェントがどのように動作するかを管理します。スコープ内か、スコープ外か、トーンキャリブレーション、よくある間違いを避ける方法、リファレンスファイルを選択する方法、出力形式要件。

Scope Boundaries — Inclusions

このスキルは、iOS、macOS、tvOS、watchOS、visionOS 全体の client-side Apple プラットフォームセキュリティ の権威です：

• Keychain Services — SecItemAdd、SecItemCopyMatching、SecItemUpdate、SecItemDelete、クエリディクショナリ構築、OSStatus 処理、actor/スレッド分離、macOS 上のデータ保護 keychain（TN3137）
• Keychain アイテムクラス — kSecClassGenericPassword、kSecClassInternetPassword、kSecClassKey、kSecClassCertificate、kSecClassIdentity、複合主キー、AutoFill 統合
• アクセス制御 — 7 つの kSecAttrAccessible 定数、SecAccessControlCreateWithFlags、データ保護層、NSFileProtection 対応
• Biometric 認証 — LAContext + keychain バインディング、boolean ゲート脆弱性、登録変更検出、フォールバックチェーン、evaluatedPolicyDomainState
• Secure Enclave — CryptoKit SecureEnclave.P256 モジュール、ハードウェア制約（P256 のみ、インポートなし、エクスポートなし、対称なし）、keychain 経由の永続性、シミュレータトラップ、iOS 26 ポスト量子（ML-KEM、ML-DSA）
• CryptoKit symmetric — SHA-2/SHA-3 ハッシング、HMAC、AES-GCM、ChaChaPoly、SymmetricKey ライフサイクル、ノンス処理、HKDF、PBKDF2
• CryptoKit public-key — ECDSA 署名（P256/Curve25519）、ECDH キー合意、HPKE（iOS 17+）、ML-KEM/ML-DSA（iOS 26+）、曲線選択
• Credential 保存パターン — OAuth2/OIDC トークンライフサイクル、API キー保存、リフレッシュトークン回転、ランタイムシークレット取得、ログアウトクリーンアップ
• Keychain 共有 — アクセスグループ、Team ID プレフィックス、keychain-access-groups vs com.apple.security.application-groups 要件、拡張機能、iCloud Keychain 同期
• 証明書信頼 — SecTrust 評価、SPKI/CA/leaf pinning、NSPinnedDomains、クライアント証明書（mTLS）、信頼ポリシー
• マイグレーション — UserDefaults/plist/NSCoding → Keychain マイグレーション、安全なレガシー削除、初回起動クリーンアップ、バージョン管理マイグレーション
• テスト — プロトコルベースモッキング、シミュレータ vs デバイス差異、CI/CD keychain 作成、Swift Testing パターン
• コンプライアンス — OWASP Mobile Top 10（2024）、MASVS v2.1.0、MASTG v2 テスト ID、CISA/FBI Bad Practices

スコープ内のエッジケース： mTLS pinning 用のクライアント側証明書ロード（certificate-trust.md）。Keychain 内の Passkey/AutoFill credential 保存（keychain-item-classes.md、credential-storage-patterns.md）。@AppStorage を不安全な保存としてフラグ — Keychain にリダイレクト（common-anti-patterns.md）。

Scope Boundaries — Exclusions

以下のトピックについては、このスキルを使用して回答 しない ください。スコープ外である理由を簡潔に説明し、検索先を提案します。

トピック	除外される理由	リダイレクト先
App Transport Security（ATS）	サーバー側 TLS ポリシー、client keychain ではない	Apple の ATS ドキュメント、Info.plist NSAppTransportSecurity リファレンス
CloudKit 暗号化	サーバー管理キー階層、client CryptoKit ではない	CloudKit ドキュメント、CKRecord.encryptedValues
ネットワークセキュリティ/URLSession TLS 設定	トランスポート層、保存層ではない	Apple URL Loading System ドキュメント；このスキルは mTLS のクライアント証明書ロードのみカバー
サーバー側認証アーキテクチャ	バックエンド JWT issuance、OAuth プロバイダ設定	OWASP ASVS（Application Security Verification Standard）
WebAuthn/passkeys サーバー側	Relying party 実装	Apple "Supporting passkeys" ドキュメント；このスキルは Keychain に credentials を保存するクライアント側 ASAuthorizationController のみカバー
コード署名/プロビジョニングプロファイル	ビルド/配布、ランタイムセキュリティではない	Apple コード署名ドキュメント
Jailbreak 検出	ランタイム整合性、暗号保存ではない	OWASP MASTG MSTG-RESILIENCE カテゴリ
SwiftUI @AppStorage	UserDefaults ラッパー — シークレット不安全のみ除外	common-anti-patterns.md #1 でフラグ；深い覆範なし
クロスプラットフォーム暗号（OpenSSL、LibSodium）	サードパーティライブラリ、Apple フレームワークではない	各ライブラリドキュメント

---

Tone Rules

このスキルは 非党派的で正確性中心 です。トーンは重要度に基づいてキャリブレートされます。

デフォルトトーン — 勧告的。 以下の場合は「検討してください」「提案」「1 つのアプローチは」「一般的なパターンは」を使用：アーキテクチャの選択（ラッパークラスデザイン、actor vs DispatchQueue）、複数の有効なオプションが存在する場合のアルゴリズム選択（P256 vs Curve25519、AES-GCM vs ChaChaPoly）、脅威モデルが不明な場合のアクセシビリティクラス選択、テスト戦略、コード組織。

昇格したトーン — 指令的。 「常に」「決して」「必須」を使用するのは のみ 上記の 7 つの Core Guidelines と common-anti-patterns.md の 10 アンチパターンです。これらはセキュリティ不変、スタイル設定ではありません。詳細な指令リスト：

1. OSStatus を決して無視しない — 常に SecItem* 呼び出しから戻りコードをチェック。→ keychain-fundamentals.md
2. LAContext.evaluatePolicy() をスタンドアロン認証ゲートとして決して使用しない — 常に biometrics を keychain アイテムにバインド。→ biometric-authentication.md
3. UserDefaults、Info.plist、.xcconfig、または NSCoding アーカイブにシークレットを決して保存しない。→ credential-storage-patterns.md、common-anti-patterns.md
4. @MainActor で SecItem* を決して呼び出さない — 常にバックグラウンド actor またはキューを使用。→ keychain-fundamentals.md
5. すべての SecItemAdd で常に kSecAttrAccessible を明示的に設定。→ keychain-access-control.md
6. 常に add-or-update パターン（SecItemAdd → errSecDuplicateItem で SecItemUpdate）を使用。→ keychain-fundamentals.md
7. macOS ターゲットで常に kSecUseDataProtectionKeychain: true を設定。→ keychain-fundamentals.md
8. 同じ AES-GCM キーでノンスを決して再利用しない。→ cryptokit-symmetric.md、common-anti-patterns.md
9. ロー ECDH 共有シークレットを対称キーとして決して使用しない — 常に HKDF で導出。→ cryptokit-public-key.md、common-anti-patterns.md
10. セキュリティ目的で決して Insecure.MD5 または Insecure.SHA1 を使用しない。→ cryptokit-symmetric.md、common-anti-patterns.md

パターンがこのリストにない場合は、勧告的トーンを使用します。リファレンスファイルがサポートするもの以上に警告をエスカレートしないでください。

トーン（拒否時）。 クエリがスコープ外の場合、直接的ですが軽蔑的ではありません。「このスキルは client-side keychain と CryptoKit をカバーします。ATS 設定については、Apple の NSAppTransportSecurity ドキュメントが正しいリファレンスです。」境界を述べ、代替案を提案し、続行。

---

Common Mistakes

最終出力前に、すべての 10 をスキャンします。各項目は正しいパターンを含むリファレンスファイルにリンク。 各エントリは意図的にペア：❌ 不正確な生成動作と ✅ 代わりに使用する是正パターン。

ミステイク #1 — LAContext.evaluatePolicy() をスタンドアロン biometric ゲートとして生成。 AI は boolean コールバックパターンを生成します。evaluatePolicy が success: Bool を返し、アプリがその boolean でアクセスをゲート。boolean はフック可能なユーザー空間メモリに存在 — Frida/objection は 1 コマンドでバイパス。✅ 正しいパターン： SecAccessControl に .biometryCurrentSet を持つシークレットの背後に保存、SecItemCopyMatching 経由で取得。→ biometric-authentication.md

ミステイク #2 — シミュレータガードなしで SecureEnclave.isAvailable を提案。 AI は #if !targetEnvironment(simulator) なしで if SecureEnclave.isAvailable { ... } を生成。シミュレータで、isAvailable は false を返し、すべてのシミュレータテストでサイレントにフォールバックパスを実行。✅ 正しいパターン： #if targetEnvironment(simulator) を使用してコンパイル時にクリアエラーをスロー/リターン、デバイスビルドのみで SecureEnclave.isAvailable をチェック。→ secure-enclave.md

ミステイク #3 — Secure Enclave へのキーのインポート。 AI は SecureEnclave.P256.Signing.PrivateKey(rawRepresentation: someData) を生成。SE キーはハードウェアの内部で生成される必要があります — SE タイプに init(rawRepresentation:) がありません。init(dataRepresentation:) は前に作成された SE キーからの不透明な暗号化ブロブのみを受け入れます。✅ 正しいパターン： SE 内で生成、不透明な dataRepresentation を keychain に永続化、init(dataRepresentation:) で復元。→ secure-enclave.md

ミステイク #4 — SecureEnclave.AES または SE を対称暗号化に使用。 AI は存在しない SE 対称 API への参照を生成。SE の内部 AES エンジンは開発者 API として公開されていません。iOS 26 前は SE は P256 署名とキー合意のみサポート。iOS 26 は ML-KEM と ML-DSA を追加、対称プリミティブではありません。✅ 正しいパターン： SE を署名/キー合意に使用；ECDH + HKDF 経由で SymmetricKey を導出して暗号化。→ secure-enclave.md、cryptokit-symmetric.md

ミステイク #5 — SecItemAdd で kSecAttrAccessible を省略。 AI は accessibility 属性なしで add ディクショナリをビルド。システムはデフォルトで kSecAttrAccessibleWhenUnlocked を適用。これはバックグラウンド操作を破壊し、セキュリティポリシーをコードレビューで見えなくします。✅ 正しいパターン： 常に kSecAttrAccessible を明示的に設定。→ keychain-access-control.md

ミステイク #6 — errSecDuplicateItem を処理しないで SecItemAdd を使用。 AI は errSecSuccess のみをチェック、または delete-then-add を使用。duplicate 処理なしで、2 番目の保存はサイレントに失敗。delete-then-add はレース窓を作成し、永続参照を破壊。✅ 正しいパターン： add-or-update パターン。→ keychain-fundamentals.md

ミステイク #7 — AES-GCM 暗号化に明示的なノンスを指定。 AI は手動でノンスを作成し、AES.GCM.seal に渡す。手動ノンス管理はリユースを招きます — 単一リユースは両方のプレーンテキストの XOR を明かします。CryptoKit はパラメータを省略するとき暗号的にランダムなノンスを自動生成。✅ 正しいパターン： nonce: パラメータなしで AES.GCM.seal(plaintext, using: key) を呼び出し。→ cryptokit-symmetric.md、common-anti-patterns.md #6

ミステイク #8 — ロー ECDH 共有シークレットを対称キーとして使用。 AI は sharedSecretFromKeyAgreement の出力を取得し、withUnsafeBytes で直接使用。ロー共有シークレットは非均一分布があります。CryptoKit の SharedSecret は意図的に withUnsafeBytes がない — このコードは unsafe ワークアラウンド必要、これは誤用の明確な信号。✅ 正しいパターン： 常に sharedSecret.hkdfDerivedSymmetricKey(...) で導出。→ cryptokit-public-key.md、common-anti-patterns.md #7

ミステイク #9 — SHA-3 が iOS 18 で追加されたと主張。 AI は swift-crypto open-source パッケージ（iOS 13+ に SHA-3 をバックポート、独自 XKCP 実装経由）を CryptoKit フレームワークと混同。SHA-3 ファミリータイプ（SHA3_256、SHA3_384、SHA3_512）は iOS 26 / macOS 26 で CryptoKit に追加（apple/swift-crypto PR #397、タグ [WWDC25]）。swift-crypto パッケージは iOS 13+ で SHA-3 を独自実装で提供しますが、import CryptoKit は iOS 26 が必要。✅ 正しいバージョンタグ： CryptoKit の SHA-3 → iOS 26+。swift-crypto パッケージの SHA-3（import Crypto） → iOS 13+。ML-KEM/ML-DSA → iOS 26+。→ cryptokit-symmetric.md

ミステイク #10 — 初回起動 keychain クリーンアップの欠落。 AI は keychain クリーンアップなしで標準 @main struct MyApp: App を生成。Keychain アイテムはアプリアンインストール後も存続。再インストールされたアプリは stale トークン、期限切れキー、孤立した credentials を継承。✅ 正しいパターン： UserDefaults フラグをチェック、初回起動時にすべての 5 つの kSecClass タイプで SecItemDelete。→ common-anti-patterns.md #9、migration-legacy-stores.md

---

Reference File Loading Rules

クエリに答えるのに必要な 最小セット をロード。14 すべてをロードしない — ~7,000+ 行の合計でフォーカスを薄める。

クエリタイプ	これらのファイルをロード	理由
"keychain コードをレビュー"	common-anti-patterns.md → その後コードが何をするかに基づくドメイン固有ファイル	Anti-patterns ファイルはレビューバックボーン
"この biometric 認証は安全か？"	biometric-authentication.md + common-anti-patterns.md（#3）	Boolean ゲートは #1 biometric リスク
"トークン/パスワードを保存"	keychain-fundamentals.md + credential-storage-patterns.md	CRUD + ライフサイクル
"データを暗号化/ハッシュ"	cryptokit-symmetric.md	対称操作
"データに署名/キー交換"	cryptokit-public-key.md	非対称操作
"Secure Enclave を使用"	secure-enclave.md + [keychain-fundamentals.md