Swift Security Expert

Keychain & Security Expert Skill

Philosophy: Non-opinionated, correctness-focused. This skill provides facts, verified patterns, and Apple-documented best practices — not architecture mandates. It covers iOS 13+ as a minimum deployment target, with modern recommendations targeting iOS 17+ and forward-looking guidance through iOS 26 (post-quantum). Every code pattern is grounded in Apple documentation, DTS engineer posts (Quinn "The Eskimo!"), WWDC sessions, and OWASP MASTG — never from memory alone. What this skill is: A reference for reviewing, improving, and implementing keychain operations, biometric authentication, CryptoKit cryptography, credential lifecycle management, certificate trust, and compliance mapping on Apple platforms. What this skill is not: A networking guide, a server-side security reference, or an App Transport Security manual. TLS configuration, server certificate management, and backend auth architecture are out of scope except where they directly touch client-side keychain or trust APIs.

Decision Tree

Determine the user's intent, then follow the matching branch. If ambiguous, ask.

                        ┌─────────────────────┐
                        │  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 (Audit Existing Code)

Goal: Systematically evaluate existing keychain/security code for correctness, security, and compliance.

Procedure:

1. Run the Top-Level Review Checklist (below) against the code under review. Score each item ✅ / ❌ / ⚠️ N/A.
2. For each ❌ failure, load the cited reference file and locate the specific anti-pattern or correct pattern.
3. Cross-check anti-patterns — scan code against all 10 entries in common-anti-patterns.md. Pay special attention to: UserDefaults for secrets (#1), hardcoded keys (#2), LAContext.evaluatePolicy() as sole auth gate (#3), ignored OSStatus (#4).
4. Check compliance — if the project requires OWASP MASVS or enterprise audit readiness, map findings to compliance-owasp-mapping.md categories M1, M3, M9, M10.
5. Report format: For each finding, state: what's wrong → which reference file covers it → the ✅ correct pattern → severity (CRITICAL / HIGH / MEDIUM).

Key reference files for review:

• Start with: common-anti-patterns.md (backbone — covers 10 most dangerous patterns)
• Then domain-specific files based on what the code does
• Finish with: compliance-owasp-mapping.md (if compliance is relevant)

Branch 2 — IMPROVE (Migrate / Modernize)

Goal: Upgrade existing code from insecure storage, deprecated APIs, or legacy patterns to current best practices.

Procedure:

1. Identify the migration type:

• Insecure storage → Keychain: Load migration-legacy-stores.md + credential-storage-patterns.md
• Legacy Security framework → CryptoKit: Load cryptokit-symmetric.md or cryptokit-public-key.md + migration-legacy-stores.md
• RSA → Elliptic Curve: Load cryptokit-public-key.md (RSA migration section)
• GenericPassword → InternetPassword (AutoFill): Load keychain-item-classes.md (migration section)
• LAContext-only → Keychain-bound biometrics: Load biometric-authentication.md
• File-based keychain → Data protection keychain (macOS): Load keychain-fundamentals.md (TN3137 section)
• Single app → Shared keychain (extensions): Load keychain-sharing.md
• Leaf pinning → SPKI/CA pinning: Load certificate-trust.md

1. Follow the migration pattern in the relevant reference file. Every migration section includes: pre-migration validation, atomic migration step, legacy data secure deletion, post-migration verification.

1. Run the domain-specific checklist from the reference file after migration completes.

1. Verify no regressions using guidance from testing-security-code.md.

Branch 3 — IMPLEMENT (Build from Scratch)

Goal: Build new keychain/security functionality correctly from the start.

Procedure:

1. Identify which domain(s) the task touches. Use the Domain Selection Guide below.
2. Load the relevant reference file(s). Follow ✅ code patterns — never deviate from them for the core security logic.
3. Apply Core Guidelines (below) to every implementation.
4. Run the domain-specific checklist before considering the implementation complete.
5. Add tests following testing-security-code.md — protocol-based abstraction for unit tests, real keychain for integration tests on device.

Domain Selection Guide:

Core Guidelines

These seven rules are non-negotiable. Every keychain/security implementation must satisfy all of them.