swift-security

# Swift Security

Use this skill for client-side Apple platform security work: Keychain Services,
access control, biometric-gated secrets, CryptoKit, Secure Enclave keys,
credential storage, certificate trust, keychain sharing, legacy secret
migration, security testing, and OWASP mobile compliance mapping.

Default to iOS 17+ and Swift concurrency examples when the deployment target is
unknown. Keep iOS 13+ compatibility notes when the user asks for older targets.
Treat iOS 26 CryptoKit post-quantum APIs as availability-gated.

## Contents

- [Workflow](#workflow)
- [Reference Loading](#reference-loading)
- [Security Invariants](#security-invariants)
- [Sibling Boundaries](#sibling-boundaries)
- [Review Checklist](#review-checklist)
- [Common Mistakes](#common-mistakes)
- [Output Rules](#output-rules)
- [References](#references)

## Workflow

Classify the request before loading references.

1. Review existing code: run the [Review Checklist](#review-checklist), then
   load [common-anti-patterns.md](references/common-anti-patterns.md) plus the
   domain reference for each failing area. Report severity, evidence, and the
   corrected pattern.
2. Improve or migrate code: identify the migration type, load the migration
   and target-domain references, preserve existing data, verify the new item,
   then remove legacy storage only after success.
3. Implement new security code: load the minimum domain references, use the
   provided correct patterns, include OSStatus handling and tests, then run the
   relevant checklist.

Do not load every reference file by default. This skill is intentionally split
for progressive disclosure; load only the files needed by the user's task.

## Reference Loading

| If the task involves | Load |
| --- | --- |
| General keychain CRUD or OSStatus handling | [keychain-fundamentals.md](references/keychain-fundamentals.md) |
| Choosing `kSecClass` or item identity | [keychain-item-classes.md](references/keychain-item-classes.md) |
| Accessibility classes or `SecAccessControl` | [keychain-access-control.md](references/keychain-access-control.md) |
| Face ID, Touch ID, or biometric-gated secrets | [biometric-authentication.md](references/biometric-authentication.md) |
| Secure Enclave keys | [secure-enclave.md](references/secure-enclave.md) |
| Hashing, HMAC, AES-GCM, ChaChaPoly, HKDF, PBKDF2 | [cryptokit-symmetric.md](references/cryptokit-symmetric.md) |
| Signing, ECDH, HPKE, ML-KEM, ML-DSA | [cryptokit-public-key.md](references/cryptokit-public-key.md) |
| OAuth tokens, API keys, logout, refresh rotation | [credential-storage-patterns.md](references/credential-storage-patterns.md) |
| App/extension keychain sharing | [keychain-sharing.md](references/keychain-sharing.md) |
| Certificate trust, SPKI pinning, mTLS | [certificate-trust.md](references/certificate-trust.md) |
| UserDefaults/plist/NSCoding migration | [migration-legacy-stores.md](references/migration-legacy-stores.md) |
| Unit, integration, simulator, device, or CI tests | [testing-security-code.md](references/testing-security-code.md) |
| OWASP MASVS/MASTG or enterprise audit mapping | [compliance-owasp-mapping.md](references/compliance-owasp-mapping.md) |
| Full security review | [common-anti-patterns.md](references/common-anti-patterns.md), then each touched domain reference |

## Security Invariants

Use directive language only for these security invariants and the matching
anti-patterns in [common-anti-patterns.md](references/common-anti-patterns.md).
For architecture choices outside this list, use advisory language.

- Never store tokens, passwords, API keys, signing keys, or refresh tokens in
  `UserDefaults`, `Info.plist`, `.xcconfig`, source code, logs, files, or
  `NSCoding` archives. Use Keychain or fetch secrets at runtime.
- Never ignore `OSStatus`. Every `SecItemAdd`, `SecItemCopyMatching`,
  `SecItemUpdate`, and `SecItemDelete` path must handle success and expected
  failures such as `errSecDuplicateItem`, `errSecItemNotFound`, and
  `errSecInteractionNotAllowed`.
- Never use `LAContext.evaluatePolicy()` as the only gate for a secret. Bind
  protected secrets to keychain items with `SecAccessControl`, then let
  keychain access trigger LocalAuthentication.
- Always set `kSecAttrAccessible` or `kSecAttrAccessControl` explicitly when
  adding keychain items.
- Always use add-or-update for persistent keychain writes. Do not delete-then-add
  as a normal update path.
- Keep `SecItem*` work off the main actor. Use an actor or serial queue for
  keychain access.
- On macOS AppKit targets, target the data protection keychain with
  `kSecUseDataProtectionKeychain: true` unless deliberately working with
  legacy file-based keychain items.
- Never reuse an AES-GCM nonce with the same key.
- Never use raw ECDH `SharedSecret` bytes as a symmetric key. Derive with HKDF
  or X9.63 derivation.
- Never use `Insecure.MD5` or `Insecure.SHA1` for security purposes.

## Sibling Boundaries

This skill owns client-side storage, cryptographic primitives, hardware-backed
keys, and trust evaluation. Route adjacent work deliberately:

- Use `authentication` for Sign in with Apple, passkeys, OAuth UI flows,
  `ASAuthorizationController`, credential state, and account sign-in UX.
- Use `cryptokit` for general CryptoKit API usage when storage, keychain,
  Secure Enclave policy, certificate trust, or compliance review is not part of
  the task.
- Use `device-integrity` for DeviceCheck and App Attest attestation/assertion
  flows.
- Use `ios-networking` for URLSession, request pipelines, ATS configuration,
  retries, caching, reachability, and transport architecture.
- Use `app-store-review` for privacy manifests, ATT, App Review guideline
  compliance, and submission readiness.

This skill may mention those areas only to identify a security handoff.

## Review Checklist

Use this checklist for code reviews and migration plans. Mark each item pass,
fail, or not applicable; for each failure, cite the reference file and