@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/swift-security/SKILL.md

@@ -1,196 +1,217 @@
 ---
 name: swift-security
-description: Use when working with iOS/macOS Keychain Services (SecItem queries, kSecClass, OSStatus errors), biometric authentication (LAContext, Face ID, Touch ID), CryptoKit (AES-GCM, ChaChaPoly, ECDSA, ECDH, HPKE, ML-KEM), Secure Enclave, secure credential storage (OAuth tokens, API keys), certificate pinning (SecTrust, SPKI), keychain sharing across apps/extensions, migrating secrets from UserDefaults or plists, or OWASP MASVS/MASTG mobile compliance on Apple platforms.
+description: "Apple client security: Keychain (SecItem, kSecClass, OSStatus, iOS, macOS), Face ID/Touch ID keychain items, CryptoKit (AES-GCM, ChaChaPoly, ECDSA, ECDH, HPKE, ML-KEM), Secure Enclave, OAuth token and API key storage, SecTrust/SPKI pinning, keychain sharing, moving secrets out of UserDefaults or plists, OWASP MASVS/MASTG. Use when writing, reviewing or migrating code that stores secrets, holds keys or evaluates trust. Not for passkeys, App Attest or App Review."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # 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.
+This skill covers the parts of an Apple-platform app that hold secrets on the
+device: the keychain, biometric gates, CryptoKit primitives, Secure Enclave keys,
+server trust, and the audit vocabulary around them.
 
-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)
+If nobody states a deployment target, write examples for iOS 17 and later with
+Swift concurrency (actors, `async`/`await`). If the user names an older target,
+keep an iOS 13 compatible path alongside (serial queue, completion handlers).
+Everything CryptoKit shipped for post-quantum work in iOS 26 (SHA-3, ML-KEM,
+ML-DSA, X-Wing, the Secure Enclave lattice types) sits behind an availability
+check; never present it as usable on earlier systems.
 
 ## Workflow
 
-Classify the request before loading references.
+Decide which of three jobs the request is before opening any reference file.
 
-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.
+1. **Review of existing code.** Walk the Review Checklist below. For every row
+   that fails, open [Anti-pattern catalog](references/common-anti-patterns.md)
+   and the domain file for that row. Report each finding with a severity, the
+   offending code as evidence, and the corrected pattern.
+2. **Improvement or migration.** Name the kind of migration (plaintext to
+   keychain, class change, accessibility change, sharing, macOS backend). Open
+   [Legacy migration](references/migration-legacy-stores.md) and the
+   file for the target domain. Keep the user's existing data readable, read the
+   new item back to prove the write, and remove the old copy only after that
+   check passes.
+3. **New implementation.** Open the fewest domain files that answer the
+   question and follow what they show. Handle every OSStatus, add tests, and
+   finish by running the matching part of the 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.
+Load references on demand. Opening all of them for every question wastes
+context and blurs the answer.
 
-## Reference Loading
+## Which Reference to Open
 
-| If the task involves | Load |
+| The task involves | Open |
 | --- | --- |
-| 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 |
+| Keychain CRUD, return types, OSStatus codes | [Keychain basics](references/keychain-fundamentals.md) |
+| Picking a `kSecClass`, primary keys, item identity | [Item classes](references/keychain-item-classes.md) |
+| `kSecAttrAccessible` values, `SecAccessControl` flags | [Access control](references/keychain-access-control.md) |
+| Face ID, Touch ID, secrets released by biometrics | [Biometrics](references/biometric-authentication.md) |
+| Keys generated in the Secure Enclave | [Enclave keys](references/secure-enclave.md) |
+| SHA-2/SHA-3, HMAC, AES-GCM, ChaChaPoly, HKDF, PBKDF2 | [Symmetric crypto](references/cryptokit-symmetric.md) |
+| Signatures, ECDH, HPKE, ML-KEM, ML-DSA | [Public-key crypto](references/cryptokit-public-key.md) |
+| OAuth tokens, API keys, refresh rotation, logout | [Credential lifecycles](references/credential-storage-patterns.md) |
+| Sharing items between an app and its extensions or sibling apps | [Sharing](references/keychain-sharing.md) |
+| `SecTrust`, SPKI pinning, client certificates (mTLS) | [Trust and pinning](references/certificate-trust.md) |
+| Moving data out of UserDefaults, plists, NSCoding archives | [Legacy migration](references/migration-legacy-stores.md) |
+| Unit, integration, Simulator, device and CI testing | [Testing](references/testing-security-code.md) |
+| OWASP MASVS, MASTG, audit evidence | [OWASP mapping](references/compliance-owasp-mapping.md) |
+| A full security review | [Anti-pattern catalog](references/common-anti-patterns.md) first, then each domain the code touches |
 
 ## 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.
+Only these rules, and the anti-patterns that break them, are phrased as "must"
+or "never". Everything else in this skill is a recommendation with trade-offs
+and should be worded that way.
+
+1. Never place refresh tokens, signing keys, API keys, passwords or tokens in
+   `UserDefaults`, `Info.plist`, `.xcconfig` values, source literals, log
+   output, plain files or `NSCoding` archives. Use the keychain, or fetch the
+   value from a server at runtime.
+2. Never discard an `OSStatus`. Every path through `SecItemAdd`,
+   `SecItemCopyMatching`, `SecItemUpdate` and `SecItemDelete` handles success
+   and the expected failures `errSecDuplicateItem`, `errSecItemNotFound` and
+   `errSecInteractionNotAllowed`.
+3. Never let the `Bool` from `LAContext.evaluatePolicy()` be the only thing
+   standing between a user and a secret. Put the secret in a keychain item
+   protected by `SecAccessControl`; reading the item makes the system run the
+   biometric check.
+4. Set `kSecAttrAccessible` or `kSecAttrAccessControl` explicitly on every add.
+5. Save with add-or-update: call `SecItemAdd`, and when it returns
+   `errSecDuplicateItem`, call `SecItemUpdate`. Deleting and re-adding is
+   reserved for changing an item's access control, which `SecItemUpdate`
+   cannot do.
+6. `SecItem*` calls must not run on the main actor. Isolate them in an actor
+   (available from iOS 13) or, in completion-handler code, a private serial
+   queue.
+7. On macOS, pass `kSecUseDataProtectionKeychain: true` unless the code is
+   deliberately working with the legacy file-based keychain.
+8. Never encrypt twice with the same AES-GCM nonce under one key.
+9. Never use the bytes of an ECDH `SharedSecret` as a key. Derive one with
+   HKDF or X9.63 first.
+10. Never let `Insecure.SHA1` or `Insecure.MD5` protect anything; they exist
+    for legacy interoperability only.
+
+## Settled Facts
+
+These answers apply across every reference file in this skill.
+
+- `errSecUserCanceled` is `-128` (the user dismissed the prompt).
+  `errSecAuthFailed` is `-25293` (authentication failed or the protected item is
+  no longer usable).
+- An item cannot be both synchronizable and `...ThisDeviceOnly`. Apple's
+  `kSecAttrSynchronizable` documentation forbids pairing it with an
+  accessibility value that ends in `ThisDeviceOnly`; the add is rejected with
+  `errSecParam` (-50) rather than quietly staying local.
+- The Simulator has no Secure Enclave. Branch on
+  `#if targetEnvironment(simulator)` at compile time and use
+  `SecureEnclave.isAvailable` as the runtime check on real hardware; do not base
+  Simulator behaviour on what the flag reports there.
+- Secure Enclave private keys that carry an access control always include
+  `.privateKeyUsage` in its flags, for example
+  `[.privateKeyUsage, .biometryCurrentSet]`.
+- Any code path that shows Face ID needs `NSFaceIDUsageDescription` in
+  `Info.plist`. The `LAContext` header asks apps to supply it, shows its string
+  the first time Face ID is used, and fails evaluations with
+  `LAError.biometryNotAvailable` once the user denies Face ID for the app. That
+  applies to keychain reads that trigger Face ID as much as to `evaluatePolicy`.
+- `arc4random` on Apple platforms is backed by a cryptographically secure
+  generator, not RC4. Its limits are a 32-bit result and the bias of `% n`. For
+  keys, nonces, salts and tokens, use `SecRandomCopyBytes`,
+  `SymmetricKey(size:)` or `SystemRandomNumberGenerator` so the size and the
+  failure path are explicit.
+- After migrating a secret, remove the plaintext copy as soon as the keychain
+  read-back succeeds. A rollback window that keeps plaintext on disk defeats the
+  migration; keep any rollback state in the keychain instead.
 
 ## 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.
+This skill owns on-device secret storage, cryptographic primitives, keys held
+in hardware, and checks of server trust. Adjacent topics appear here only to
+point at the right skill:
+
+- `authentication`: passkeys, Sign in with Apple, OAuth sign-in flows,
+  `ASAuthorizationController`, credential state, sign-in UX, and `LAContext`
+  prompts and policy that do not guard a keychain item.
+- `cryptokit`: CryptoKit questions with no storage, keychain, Secure Enclave,
+  trust or compliance angle.
+- `device-integrity`: DeviceCheck and App Attest attestations and assertions.
+- `ios-networking`: URLSession, request pipelines, ATS settings, retries,
+  caching, reachability and transport design.
+- `app-store-review`: privacy manifests, ATT, App Review guidelines and
+  submission readiness.
 
 ## 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 severity.
-
-- Secrets are not stored in `UserDefaults`, plists, source, logs, files, or
-  archives.
-- Every `SecItem*` call checks `OSStatus` and handles common recoverable errors.
-- Biometric access to secrets is keychain-bound with `SecAccessControl`, not a
-  standalone `Bool` from `LAContext.evaluatePolicy()`.
-- Keychain add dictionaries set an explicit accessibility policy.
-- Keychain writes use add-or-update rather than delete-then-add.
-- Keychain work is isolated from UI/main-actor code.
-- The selected `kSecClass` matches the item type and primary-key attributes.
-- CryptoKit code avoids nonce reuse, raw shared-secret use, weak hashes, and
-  hardcoded keys.
-- Secure Enclave code checks availability, handles simulator/device differences,
-  persists only `dataRepresentation`, and designs for device-bound keys.
-- App/extension sharing uses full Team ID access groups and matching
-  entitlements on every target.
-- Certificate trust uses current `SecTrust` APIs, validates hostname/policy, and
-  uses SPKI or CA pinning when pinning is required.
-- macOS keychain code intentionally chooses data protection or file-based
-  keychain behavior.
-- Tests cover success, duplicate, missing item, locked-device, simulator/device,
-  and migration paths where applicable.
-- OWASP MASVS/MASTG mappings are included when compliance is requested.
+Mark each row pass, fail or n/a. A fail names the reference file and a severity.
+
+- [ ] No secret sits in source code, `UserDefaults`, a plist, a log line, a plain file or an archive.
+- [ ] Each `SecItem*` call inspects its `OSStatus` and handles the recoverable cases.
+- [ ] Biometric access to a secret goes through a `SecAccessControl` keychain item, not an `evaluatePolicy()` Bool.
+- [ ] Add dictionaries carry an explicit accessibility value.
+- [ ] Saves are add-or-update; delete-then-add appears only for access-control changes.
+- [ ] Keychain calls run away from the UI and the main actor.
+- [ ] The `kSecClass` fits the item and its primary-key attributes are all set.
+- [ ] CryptoKit use avoids nonce reuse, raw shared secrets, weak hashes and embedded keys.
+- [ ] Secure Enclave code checks availability, separates Simulator from device, stores only `dataRepresentation`, and assumes keys never leave the device.
+- [ ] App and extension sharing uses Team ID prefixed access groups with matching entitlements on every target.
+- [ ] Trust evaluation uses current `SecTrust` APIs, checks the host name and policy, and pins SPKI or a CA when pinning is required.
+- [ ] On macOS, the choice between the file-based keychain and the data protection keychain is deliberate.
+- [ ] Tests exercise the happy path, a duplicate add, an absent item, a locked device, Simulator against hardware, and migration where it applies.
+- [ ] A MASVS/MASTG mapping is included when compliance was asked for.
 
 ## Common Mistakes
 
-- Generating partial keychain examples without duplicate handling or
-  `errSecItemNotFound` handling.
-- Adding biometric UI but leaving the secret readable without keychain access
-  control.
-- Choosing `kSecAttrAccessibleWhenUnlocked` implicitly by omitting the attribute.
-- Using `kSecAttrAccessibleAlways` or
-  `kSecAttrAccessibleAlwaysThisDeviceOnly`, both deprecated.
-- Mixing `kSecAttrAccessible` and `kSecAttrAccessControl` on the same add query.
-- Treating Secure Enclave keys as importable, exportable, syncable, or suitable
-  for symmetric encryption.
-- Claiming SHA-3, ML-KEM, ML-DSA, or X-Wing CryptoKit APIs are available before
-  iOS 26.
-- Treating HPKE as available before iOS 17.
-- Implementing certificate pinning by hashing only raw key bytes instead of the
-  correct SPKI representation.
-- Expanding this skill into account-login, networking, App Attest, or App Store
-  review guidance instead of handing off to sibling skills.
+- Keychain snippets that stop at `SecItemAdd` with no duplicate branch or no
+  `errSecItemNotFound` branch.
+- A Face ID prompt bolted onto the UI while the secret itself remains readable
+  without any keychain access control.
+- Leaving out `kSecAttrAccessible`, which silently means
+  `kSecAttrAccessibleWhenUnlocked`.
+- Using `kSecAttrAccessibleAlways` or `kSecAttrAccessibleAlwaysThisDeviceOnly`;
+  both are deprecated.
+- One add dictionary that carries both `kSecAttrAccessControl` and
+  `kSecAttrAccessible`.
+- Expecting to import, export or sync an enclave key, or asking the enclave to
+  perform symmetric encryption.
+- Offering the CryptoKit ML-KEM, ML-DSA, X-Wing or SHA-3 types on systems older
+  than iOS 26.
+- Offering HPKE on systems older than iOS 17.
+- Computing a pin over bare public-key bytes instead of the DER-encoded
+  SubjectPublicKeyInfo.
+- Wandering into sign-in flows, networking stacks, App Attest or App Review
+  instead of handing those parts to the sibling skill.
 
 ## Output Rules
 
-- For security findings, state severity: CRITICAL for exploitable secret or
-  cryptography failures, HIGH for silent security boundary/data-loss issues, and
-  MEDIUM for brittle or incomplete hardening.
-- Include wrong and corrected code examples for implementation reviews when a
-  concrete anti-pattern is present.
-- Include minimum iOS/macOS availability when recommending versioned APIs.
-- Cite the reference file that supports each substantive security pattern.
-- For keychain code, include `OSStatus` handling and explicit accessibility in
-  examples.
-- For implementation or migration answers, end with `## Reference Files` and
-  list the loaded references with a one-line purpose.
-- Do not invent WWDC session numbers or source citations. If a claim is not
-  present in the loaded references or official Apple documentation, say it needs
-  verification.
+- Severity: **CRITICAL** is an exploitable secret exposure or broken crypto;
+  **HIGH** is a silent break in a security boundary or a data-loss path;
+  **MEDIUM** is hardening that is brittle or incomplete.
+- When reviewing code with a concrete anti-pattern, show the wrong code and the
+  corrected code.
+- State the minimum iOS and macOS version whenever you recommend an API that is
+  versioned.
+- Name the reference file that backs each substantive security pattern.
+- Keychain samples always show `OSStatus` handling and an explicit
+  accessibility value.
+- Close implementation and migration answers with a `## Reference Files`
+  section: each reference you loaded plus one line on why.
+- Do not make up WWDC session numbers or citations. When a claim has no source
+  at hand, say it needs verification.
 
 ## References
 
-- [keychain-fundamentals.md](references/keychain-fundamentals.md) - SecItem CRUD, OSStatus handling, add-or-update, macOS data protection keychain.
-- [keychain-item-classes.md](references/keychain-item-classes.md) - `kSecClass` selection, primary keys, certificates, identities.
-- [keychain-access-control.md](references/keychain-access-control.md) - Accessibility constants, `SecAccessControl`, background access, data protection.
-- [biometric-authentication.md](references/biometric-authentication.md) - Keychain-bound biometrics, `LAContext`, enrollment-change handling.
-- [secure-enclave.md](references/secure-enclave.md) - Secure Enclave constraints, persistence, biometric keys, iOS 26 PQ APIs.
-- [cryptokit-symmetric.md](references/cryptokit-symmetric.md) - SHA, HMAC, AES-GCM, ChaChaPoly, HKDF, PBKDF2.
-- [cryptokit-public-key.md](references/cryptokit-public-key.md) - Signing, key agreement, HPKE, ML-KEM, ML-DSA, key formats.
-- [credential-storage-patterns.md](references/credential-storage-patterns.md) - OAuth tokens, API keys, rotation, logout cleanup.
-- [keychain-sharing.md](references/keychain-sharing.md) - Access groups, extensions, iCloud sync, macOS access groups.
-- [certificate-trust.md](references/certificate-trust.md) - SecTrust, SPKI/CA pinning, `NSPinnedDomains`, client certificates.
-- [migration-legacy-stores.md](references/migration-legacy-stores.md) - UserDefaults/plist/NSCoding migration and cleanup.
-- [common-anti-patterns.md](references/common-anti-patterns.md) - Review backbone for insecure generated code.
-- [testing-security-code.md](references/testing-security-code.md) - Protocol mocks, real keychain tests, CI/device split.
-- [compliance-owasp-mapping.md](references/compliance-owasp-mapping.md) - OWASP Mobile Top 10, MASVS, MASTG evidence mapping.
+- [Keychain basics](references/keychain-fundamentals.md): the four SecItem calls, return types, OSStatus handling, actor wrapper, macOS backends.
+- [Item classes](references/keychain-item-classes.md): the five item classes, their primary keys, keys, certificates and identities.
+- [Access control](references/keychain-access-control.md): accessibility constants, `SecAccessControl` flags, background access, file protection.
+- [Biometrics](references/biometric-authentication.md): keychain-bound biometrics, `LAContext`, enrollment changes.
+- [Enclave keys](references/secure-enclave.md): enclave limits, CryptoKit `SecureEnclave`, key persistence, iOS 26 post-quantum types.
+- [Symmetric crypto](references/cryptokit-symmetric.md): hashing, HMAC, AES-GCM, ChaChaPoly, HKDF, PBKDF2.
+- [Public-key crypto](references/cryptokit-public-key.md): ECDSA, ECDH, HPKE, ML-KEM, ML-DSA, key formats, moving off RSA.
+- [Credential lifecycles](references/credential-storage-patterns.md): OAuth tokens, API keys, refresh rotation, logout cleanup.
+- [Sharing](references/keychain-sharing.md): access groups, entitlements, extensions, iCloud Keychain, macOS groups.
+- [Trust and pinning](references/certificate-trust.md): `SecTrust`, SPKI and CA pinning, `NSPinnedDomains`, client certificates.
+- [Legacy migration](references/migration-legacy-stores.md): moving secrets out of UserDefaults, plists and archives, then cleaning up.
+- [Anti-pattern catalog](references/common-anti-patterns.md): the catalog of insecure patterns that drives a review.
+- [Testing](references/testing-security-code.md): protocol mocks, real keychain tests, the CI and device split.
+- [OWASP mapping](references/compliance-owasp-mapping.md): OWASP Mobile Top 10, MASVS and MASTG evidence.

package/pipeline/skills/shared/external/swift-security/evals/evals.json

@@ -4,44 +4,44 @@
     {
       "id": 0,
       "name": "keychain-token-review",
-      "prompt": "Review this iOS token storage helper before we ship it. It saves an OAuth refresh token with `UserDefaults.standard.set(refreshToken, forKey: \"refresh\")`, writes access tokens with `SecItemAdd(query as CFDictionary, nil)` but ignores the returned OSStatus, omits `kSecAttrAccessible`, and calls `SecItemDelete` before every save to avoid duplicates. What is wrong, what severity would you assign, and what should the corrected Keychain pattern require?",
-      "expected_output": "A security review that flags plaintext token storage, ignored OSStatus, missing accessibility, and delete-then-add as findings; assigns severity; and requires Keychain add-or-update with explicit accessibility and recoverable error handling.",
+      "prompt": "Review this helper from our fitness app. `SessionVault.save(refresh:)` keeps a fallback copy via `UserDefaults.standard.set(token, forKey: \"rt\")`, then calls `SecItemDelete` on the same service and account followed by `SecItemAdd` with class, service, account and value data. The return value of `SecItemAdd` is ignored and no accessibility attribute is passed. Tell us what is wrong and how to fix it.",
+      "expected_output": "Flags the UserDefaults copy of the refresh token as CRITICAL or HIGH and says it must be removed. Points out the ignored OSStatus and shows handling for errSecDuplicateItem, errSecItemNotFound and errSecInteractionNotAllowed. Adds an explicit kSecAttrAccessible value (or a SecAccessControl) to the add dictionary. Replaces delete-then-add with add, then SecItemUpdate when the add reports a duplicate. Shows wrong and corrected code and names the reference files used.",
       "files": [],
-      "assertions": [
-        "Flags the refresh token in UserDefaults as a critical or high-severity insecure secret storage finding.",
-        "Requires checking OSStatus for SecItem calls and specifically handling errSecDuplicateItem, errSecItemNotFound, and errSecInteractionNotAllowed where relevant.",
-        "Requires an explicit kSecAttrAccessible or SecAccessControl policy for added items.",
-        "Rejects delete-then-add as the normal update strategy and recommends add-or-update with SecItemUpdate on errSecDuplicateItem.",
-        "Cites or names the relevant swift-security reference files for Keychain fundamentals, credential storage, access control, or common anti-patterns."
+      "expectations": [
+        "Rates the refresh token stored in UserDefaults as critical or high severity",
+        "Adds OSStatus checks that cover errSecDuplicateItem, errSecItemNotFound and errSecInteractionNotAllowed",
+        "Sets kSecAttrAccessible explicitly, or uses a SecAccessControl, on the add",
+        "Rejects the delete-then-add save and calls SecItemUpdate when SecItemAdd returns a duplicate",
+        "Cites the reference files that support the fixes"
       ]
     },
     {
       "id": 1,
       "name": "biometric-secret-boundary",
-      "prompt": "A banking app wants Face ID before showing an account number. The current plan is to call `LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, localizedReason: ...)`, check the returned Bool, then read the account number from UserDefaults. They also forgot `NSFaceIDUsageDescription`. Write the correction plan and include the important iOS API constraints.",
-      "expected_output": "A correction plan that rejects the standalone LAContext Bool gate, moves the secret into a Keychain item protected by SecAccessControl, mentions Face ID usage description, handles enrollment changes, and states availability constraints for the biometric APIs.",
+      "prompt": "Our banking app shows the full card number after `LAContext().evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, localizedReason:)` returns true. The number itself lives in UserDefaults and Info.plist has no Face ID entry. Is this acceptable, and what should we change?",
+      "expected_output": "Says a Bool from evaluatePolicy is not a security boundary and can be forced true at runtime. Moves the card number into the keychain, guarded by a SecAccessControl using .biometryCurrentSet (or .userPresence where passcode fallback is wanted) so the read itself triggers the prompt. Adds NSFaceIDUsageDescription to Info.plist. Explains that .biometryCurrentSet makes the item unreadable after an enrollment change, how evaluatedPolicyDomainState detects that, and the recovery path. Cites biometric-authentication.md and keychain-access-control.md.",
       "files": [],
-      "assertions": [
-        "States that LAContext.evaluatePolicy alone must not release or protect the stored secret.",
-        "Requires storing the account number or token in Keychain behind SecAccessControl with an appropriate flag such as .biometryCurrentSet or .userPresence.",
-        "Mentions NSFaceIDUsageDescription as required for Face ID use.",
-        "Explains the enrollment-change effect of .biometryCurrentSet or evaluatedPolicyDomainState and the need for recovery/re-enrollment handling.",
-        "Cites or names biometric-authentication and keychain-access-control references."
+      "expectations": [
+        "Rejects the evaluatePolicy Bool as the only gate",
+        "Stores the secret in the keychain behind SecAccessControl using .biometryCurrentSet or .userPresence",
+        "Mentions adding NSFaceIDUsageDescription to Info.plist",
+        "Says what an enrollment change does to a .biometryCurrentSet item, covers detection through evaluatedPolicyDomainState, and a recovery flow",
+        "Cites biometric-authentication.md and keychain-access-control.md"
       ]
     },
     {
       "id": 2,
       "name": "security-sibling-boundary",
-      "prompt": "A team asks for one security checklist covering Sign in with Apple, passkey server verification, App Attest assertions, URLSession quantum-secure TLS, custom end-to-end document encryption on iOS 26, Keychain refresh-token storage, Secure Enclave keys, and App Store privacy manifests. Give a concise scope review for what swift-security should answer directly and what should be handed to sibling skills.",
-      "expected_output": "A boundary-aware scope review that keeps Keychain, CryptoKit, Secure Enclave, credential storage, and certificate trust in swift-security; routes auth UI/server passkeys, App Attest, URLSession/TLS transport, and App Store privacy manifests to sibling skills; and names iOS 26 CryptoKit availability for custom quantum-secure workflows.",
+      "prompt": "Give us a security checklist for our next release. It covers: refresh-token storage in the keychain, the access policy for a Secure Enclave signing key, pinning our API certificate, end-to-end encrypting chat messages with CryptoKit, adding Sign in with Apple and passkeys, verifying OAuth tokens on the relying party, App Attest, URLSession TLS settings, and our privacy manifest. We also want to try ML-KEM.",
+      "expected_output": "Treats four items as in scope here: keychain refresh-token storage, the access policy of the enclave key, certificate trust, and CryptoKit encryption on the client. Hands passkeys, Sign in with Apple, OAuth and relying-party verification to authentication, App Attest and DeviceCheck to device-integrity, URLSession and TLS configuration to ios-networking (the custom CryptoKit end-to-end layer stays here), and the privacy manifest to app-store-review. Notes that X-Wing, ML-DSA, ML-KEM, SHA-3 and the Secure Enclave post-quantum types need iOS 26.",
       "files": [],
-      "assertions": [
-        "Keeps Keychain refresh-token storage, Secure Enclave key policy, certificate trust, and client-side CryptoKit guidance in swift-security scope.",
-        "Routes Sign in with Apple, passkey registration/assertion UI, OAuth account flows, and passkey relying-party verification to authentication rather than expanding swift-security.",
-        "Routes App Attest and DeviceCheck assertions to device-integrity.",
-        "Routes URLSession transport architecture or TLS configuration to ios-networking while noting swift-security can discuss custom CryptoKit end-to-end encryption.",
-        "Routes App Store privacy manifests and submission compliance to app-store-review.",
-        "Mentions iOS 26 availability for ML-KEM, ML-DSA, X-Wing, SHA-3, or SecureEnclave post-quantum APIs when discussing custom document encryption."
+      "expectations": [
+        "Treats keychain token storage, the enclave key policy, certificate trust and client-side CryptoKit as in scope",
+        "Routes passkeys, Sign in with Apple, OAuth and relying-party verification to authentication",
+        "Routes App Attest and DeviceCheck to device-integrity",
+        "Sends URLSession and TLS settings to ios-networking and keeps the app's own end-to-end CryptoKit layer here",
+        "Routes privacy manifests to app-store-review",
+        "Says X-Wing, ML-DSA, ML-KEM, SHA-3 and the enclave post-quantum APIs require iOS 26"
       ]
     }
   ]