If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/evgenyneu/keychain-swift shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 18 active contributors
• MIT licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 74% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live evgenyneu/keychain-swift repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/evgenyneu/keychain-swift.

What it runs against: a local clone of evgenyneu/keychain-swift — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in evgenyneu/keychain-swift | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 744 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of evgenyneu/keychain-swift. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/evgenyneu/keychain-swift.git
#   cd keychain-swift
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of evgenyneu/keychain-swift and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "evgenyneu/keychain-swift(\\.git)?\\b" \\
  && ok "origin remote is evgenyneu/keychain-swift" \\
  || miss "origin remote is not evgenyneu/keychain-swift (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Sources/KeychainSwift.swift" \\
  && ok "Sources/KeychainSwift.swift" \\
  || miss "missing critical file: Sources/KeychainSwift.swift"
test -f "Sources/KeychainSwiftAccessOptions.swift" \\
  && ok "Sources/KeychainSwiftAccessOptions.swift" \\
  || miss "missing critical file: Sources/KeychainSwiftAccessOptions.swift"
test -f "Sources/TegKeychainConstants.swift" \\
  && ok "Sources/TegKeychainConstants.swift" \\
  || miss "missing critical file: Sources/TegKeychainConstants.swift"
test -f "Tests/KeychainSwiftTests/KeychainSwiftTests.swift" \\
  && ok "Tests/KeychainSwiftTests/KeychainSwiftTests.swift" \\
  || miss "missing critical file: Tests/KeychainSwiftTests/KeychainSwiftTests.swift"
test -f "KeychainSwift.podspec" \\
  && ok "KeychainSwift.podspec" \\
  || miss "missing critical file: KeychainSwift.podspec"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 744 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~714d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/evgenyneu/keychain-swift"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

KeychainSwift is a lightweight wrapper around Apple's Security framework that simplifies storing and retrieving sensitive text, data, and booleans in the iOS/macOS Keychain. It reduces verbose Keychain API calls to simple set() and get() methods while supporting iCloud synchronization, access groups for app sharing, and configurable security levels across iOS, macOS, tvOS, and watchOS. Single-module architecture: Sources/KeychainSwift.swift is the core API wrapper (~54KB), with related files Sources/KeychainSwiftAccessOptions.swift (security policies) and Sources/TegKeychainConstants.swift (constants). Tests/ folder mirrors functionality with platform-specific test suites. Demo/ contains a working iOS app demonstrating all features. Distrib/KeychainSwiftDistrib.swift is a single-file distributable version for direct source inclusion.

iOS/macOS app developers who need to securely store user credentials, authentication tokens, and sensitive data without wrestling with Apple's low-level Security framework APIs. Developers integrating with CocoaPods, Carthage, or Swift Package Manager who want a drop-in solution with minimal dependencies.

Production-ready and actively maintained. The library has reached version 24.0 (visible in README and podspec), includes comprehensive test coverage across platforms (AccessGroupTests, ConcurrencyTests, SynchronizableTests, etc.), and supports multiple distribution methods (CocoaPods, Carthage, SPM). The presence of platform-specific schemes (iOS, macOS, tvOS, watchOS) and a dedicated Demo app indicates mature, platform-tested code.

Low risk for a single-purpose library. It depends only on Apple's first-party Security framework (no external dependencies visible), making it stable. The single-maintainer structure (evgenyneu) is a minor concern, but the simple, focused scope and strong test coverage mitigate this. No breaking changes visible in CHANGELOG structure suggests careful versioning.

The project appears stably maintained with well-organized test structure. The presence of ConcurrencyTests.swift suggests recent attention to Swift concurrency patterns. Multiple Xcode schemes for different platforms (KeychainSwift.xcscheme, KeychainSwift-macOS.xcscheme, etc.) indicate ongoing multi-platform support. Privacy manifest (PrivacyInfo.xcprivacy) suggests recent updates for iOS 17+ compliance.

git clone https://github.com/evgenyneu/keychain-swift.git
cd keychain-swift
open KeychainSwift.xcodeproj
# Then select scheme 'KeychainSwift' and run tests (Cmd+U) or 'Demo' and run app (Cmd+R)

Alternatively, add to Podfile: pod 'KeychainSwift', '~> 24.0' and run pod install.

Daily commands: Open KeychainSwift.xcodeproj in Xcode, select scheme 'Demo', and press Cmd+R. Or run tests with Cmd+U. For package manager users: CocoaPods (pod install then open .xcworkspace), Carthage (carthage update), or SPM (File > Add Packages, paste GitHub URL).

• Sources/KeychainSwift.swift — Core library implementation containing KeychainSwift class with all read/write/delete operations—every contributor must understand the main API surface.
• Sources/KeychainSwiftAccessOptions.swift — Defines security access options (kSecAttrAccessible flags) that control when keychain items can be accessed—critical for security decisions.
• Sources/TegKeychainConstants.swift — Maps Swift-friendly names to native Keychain Security framework constants—essential reference for understanding low-level keychain interactions.
• Tests/KeychainSwiftTests/KeychainSwiftTests.swift — Primary test suite covering core functionality, access groups, and synchronization—demonstrates expected behavior and integration patterns.
• KeychainSwift.podspec — CocoaPods package manifest defining dependencies, platforms, and distribution—required for understanding deployment and version compatibility.
• Package.swift — Swift Package Manager manifest for SPM-based installations—shows module structure and platform support declarations.
• Demo/ViewController.swift — iOS demo application showing real-world usage patterns of KeychainSwift API.

Add a new Keychain access option

1. Add the new security attribute constant to TegKeychainConstants.swift as a static let with the kSec* constant value (Sources/TegKeychainConstants.swift)
2. Create a new case in the KeychainSwiftAccessOptions enum mapping to your constant (Sources/KeychainSwiftAccessOptions.swift)
3. Update the accessOptionToString() method in KeychainSwiftAccessOptions.swift to return the constant string for your new case (Sources/KeychainSwiftAccessOptions.swift)
4. Add unit test in AccessGroupTests.swift or create new test file to verify the new option applies correctly (Tests/KeychainSwiftTests/AccessGroupTests.swift)

Add support for a new Apple platform (tvOS, watchOS variant)

1. Create a new scheme in KeychainSwift.xcodeproj matching the platform (already exists: KeychainSwift-tvOS.xcscheme, KeychainSwift-watchOS.xcscheme) (KeychainSwift.xcodeproj/xcshareddata/xcschemes)
2. Update Package.swift to include new platform in the package platforms array (Package.swift)
3. Update KeychainSwift.podspec to add the platform to the podspec deployment targets (KeychainSwift.podspec)
4. Add platform-specific test file in Tests/KeychainSwiftTests/ if needed for platform-unique behaviors (Tests/KeychainSwiftTests/KeychainSwiftTests.swift)

Add a new query/retrieval method (e.g., get all keys matching pattern)

1. Implement the method in KeychainSwift.swift following the pattern of existing methods (queryKeychain with parameters, parse results) (Sources/KeychainSwift.swift)
2. Add the required Security framework query dictionary constants to TegKeychainConstants.swift if new attributes are needed (Sources/TegKeychainConstants.swift)
3. Create a new test file in Tests/KeychainSwiftTests/ or extend KeychainSwiftTests.swift with comprehensive test cases (Tests/KeychainSwiftTests/KeychainSwiftTests.swift)
4. Update README.md with usage example of the new method (README.md)

Add a new demo feature to showcase functionality

1. Add UI controls (buttons, text fields) to Demo/Base.lproj/Main.storyboard (Demo/Base.lproj/Main.storyboard)
2. Implement IBAction methods in Demo/ViewController.swift to demonstrate the KeychainSwift API (Demo/ViewController.swift)
3. Mirror the changes to macOS Demo/Base.lproj/Main.storyboard and macOS Demo/ViewController.swift for consistency (macOS Demo/ViewController.swift)

• Apple Security Framework (SecItem functions)* — Only official API for accessing device keychain on iOS/macOS/tvOS/watchOS; provides hardware-backed encryption and biometric auth integration
• Swift with Objective-C bridge — Security framework is Objective-C; Swift wrapper provides type safety and modern API while maintaining access to all underlying features
• CocoaPods + SPM dual distribution — Maximizes adoption across legacy (CocoaPods) and modern (SPM) dependency ecosystems; no external runtime dependencies
• Multi-platform targets (iOS/macOS/tvOS/watchOS) — Single codebase leverages identical Security framework API across all Apple platforms; compiled independently per platform

• Synchronous API design (no async/await wrappers provided)

  • Why: Keychain operations are fast (1-5ms) and should not block main thread; developers should call from background queue if needed
  • Consequence: Simple API surface but requires caller to manage threading; no Combine/async helpers in core library

• String-only storage by default (no Data methods in main API)

  • Why: Simplifies common case (passwords, API keys, tokens) and reduces API surface
  • Consequence: Binary data must be base64-encoded by caller; generic Data storage not offered

• Per-key access options (set at time of write, not global)

  • Why: Allows fine-grained control (e.g., some keys accessible when locked, others only when unlocked)
  • Consequence: Access level must be respecified on SecItemUpdate; cannot change retroactively without delete+rewrite

• Silent failures for missing keys (get returns nil, not error)

  • Why: Keychain absence is common/expected state; reduces error handling boilerplate
  • Consequence: Cannot distinguish 'not found' from 'access denied'—both return nil

• Real-time synchronization of keychain changes across devices (iCloud Keychain is Apple's domain; this library only sets kSecAttrSynchronizable flag)
• Biometric/Touch ID/Face ID authentication integration (Security framework handles this internally when kSecAttrAccessible option is set)
• Certificate/key generation or cryptographic operations (keychain is for storage only; use CryptoKit for crypto)
• Encryption of arbitrary large files (keychain designed for small secrets <4KB; not a file encryption library)
• Cross-platform support outside Apple ecosystem (iOS/macOS/tvOS/

1. Keychain access requires entitlements: Apps must include Keychain entitlements (Capabilities > Keychain Sharing in Xcode) or queries silently fail. 2. Simulator vs. device behavior: Keychain behaves differently on simulator (persists between app reinstalls) vs. physical device (wiped on app delete). 3. Data type coercion: The library stores everything as strings internally; Data types are base64-encoded, so raw binary comparisons may fail. 4. iCloud sync delay: Setting synchronizable(true) doesn't guarantee immediate iCloud sync; may take minutes and requires user iCloud login. 5. Access group limitations: Access groups only work with provisioning profiles that explicitly enable them; local testing may fail if misconfigured. 6. watchOS/tvOS Keychain limits: Keychain on watchOS is significantly limited (small storage quota); not suitable for caching large secrets.

• Keychain (Apple Security Framework) — Core iOS/macOS secure storage system that KeychainSwift wraps; understanding the underlying kSecItem* APIs (SecItemAdd, SecItemCopyMatching, SecItemDelete) explains why this library is necessary and its limitations
• Data Protection / File Protection Classes — KeychainSwift's accessible() access option maps to Apple's kSecAttrAccessible protection levels; critical for understanding when stored credentials are accessible (locked device vs. unlocked)
• Keychain Access Groups — Enables credential sharing between multiple apps from the same developer; KeychainSwift supports this via accessGroup() but requires entitlements and code signing setup
• iCloud Keychain Synchronization — KeychainSwift's synchronizable(true) option syncs secrets across user devices; requires understanding eventual consistency, iCloud login state, and network conditions
• Base64 Encoding for Binary Data — KeychainSwift converts Data to Base64 strings for Keychain storage (Keychain prefers string/CFData, not raw binary); relevant when integrating with other crypto libraries or decoding stored secrets
• Swift Concurrency (async/await) — Presence of ConcurrencyTests.swift indicates the library supports Swift concurrency; important for understanding thread-safety of set/get/delete operations in modern async contexts
• Platform Conditional Compilation — KeychainSwift uses #if os(iOS), #if os(macOS), etc. to support 4 platforms (iOS, macOS, tvOS, watchOS) with different Keychain capabilities; relevant for understanding cross-platform code organization

• kishikawakatsumi/KeychainAccess — Alternative Keychain wrapper with similar Swift API and broader attribute customization; direct competitor in the ecosystem
• apple/swift-crypto — Apple's official crypto library often used in conjunction with Keychain for securing stored data; complements this library for full end-to-end security
• realm/realm-swift — Mobile database often paired with Keychain for complete secure data persistence (Keychain for secrets, Realm for large encrypted datasets)
• MessagePack/msgpack-swift — Serialization library useful for storing complex objects in Keychain (encode struct to MessagePack binary, store as Data via KeychainSwift)
• pointfreeco/swift-dependencies — Dependency injection framework compatible with KeychainSwift for testable credential management across a Swift app architecture

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive async/await tests for KeychainSwift operations

The repo contains a ConcurrencyTests.swift file but given the library supports iOS 13+ (async/await), there's opportunity to expand concurrency test coverage. The existing tests in Tests/KeychainSwiftTests/ appear to focus on synchronous operations. New async/await tests would ensure thread-safety and proper behavior under concurrent keychain access patterns, which is critical for modern Swift apps.

• [ ] Review existing Tests/KeychainSwiftTests/ConcurrencyTests.swift to identify coverage gaps
• [ ] Add async/await variants for set/get/delete operations using structured concurrency
• [ ] Test race conditions with multiple concurrent keychain reads/writes
• [ ] Test cancellation behavior with Task.cancel()
• [ ] Run tests on macOS, iOS, tvOS, and watchOS targets to ensure platform compatibility

Add integration tests for Keychain access group and iCloud synchronization across app targets

The repo has AccessGroupTests.swift and SynchronizableTests.swift, but they appear to be unit tests only. There's no evidence of integration tests validating that access groups work correctly between app extensions and the main app, or that iCloud synchronization actually persists data. These are critical real-world scenarios that mock-based testing cannot fully validate.

• [ ] Create a new test target with an App Extension (e.g., Share Extension or Notification Service) in KeychainSwift.xcodeproj
• [ ] Write integration tests in Tests/ that verify data set by the main app is readable by the extension using the same access group identifier
• [ ] Add tests validating kSecAttrSynchronizable behavior persists across app launches (requires manual iCloud setup in tests)
• [ ] Document in CONTRIBUTING.md how to run integration tests with proper provisioning profiles
• [ ] Test on both iOS and macOS platforms

Add GitHub Actions CI workflow for running tests on multiple Swift/iOS versions

The repo has multiple Xcode schemes (Demo.xcscheme, KeychainSwift.xcscheme, macOS-Tests.xcscheme, etc.) but no visible CI/CD workflow file. There's no .github/workflows directory mentioned in the file structure. A GitHub Actions workflow would ensure tests pass on multiple Swift versions and platforms before PRs are merged, reducing regressions.

• [ ] Create .github/workflows/tests.yml to run Tests/KeychainSwiftTests/ on iOS, macOS, tvOS, and watchOS
• [ ] Configure matrix strategy to test against multiple Xcode versions (14, 15, latest)
• [ ] Add step to run xcodebuild test for KeychainSwift.xcodeproj scheme on iOS simulator
• [ ] Add separate step for macOS tests using the 'macOS Tests' scheme
• [ ] Configure workflow to run on push to main and on pull requests
• [ ] Add badge to README.md linking to workflow status

• Add Swift concurrency async/await variants for all public methods (set/get/delete/clear). The ConcurrencyTests.swift file exists but likely the main API still has callback-based alternatives; refactor Sources/KeychainSwift.swift to make async the primary interface.
• Expand test coverage for macOS-specific code in Tests/KeychainSwiftTests/macOS Tests/macOS_Tests.swift — add tests for access group isolation, cross-app keychain sharing, and verification that macOS behaves identically to iOS.
• Document access group setup in README with step-by-step Xcode capability configuration. Currently README mentions access groups feature but doesn't explain how to enable them in project settings or troubleshoot failures (common source of bugs).

KeychainSwift appears to be a well-intentioned wrapper around Apple's Keychain framework. Primary security concerns are: (1) potential injection vulnerabilities if string interpolation is used instead of proper parameterization in Keychain queries, (2) lack of visible input validation on keychain keys, and (3) potential information disclosure through error messages. The codebase shows good structure with dedicated access control options file, but source code review is needed to verify proper use of SecItemAdd/Update/Delete APIs and secure defaults. No hardcoded secrets, external dependencies, or infrastructure issues detected. The library's security posture depends heavily on proper implementation details not visible in the file structure alone.

• Medium · Potential Keychain Query Injection via String Interpolation — Sources/KeychainSwift.swift. The codebase handles Keychain queries with user-supplied data. If the KeychainSwift.swift implementation uses string concatenation or direct interpolation for building Keychain queries without proper parameterization, it could be vulnerable to query injection attacks where specially crafted input could modify query behavior. Fix: Review KeychainSwift.swift to ensure all Keychain query parameters are properly escaped and use SecItemAdd/SecItemUpdate/SecItemDelete APIs with dictionary parameters rather than string concatenation. Validate and sanitize all user-supplied input used as Keychain keys.
• Medium · Missing Input Validation on Keychain Keys — Sources/KeychainSwift.swift. Without visible source code review, it's unclear if the library validates keychain item keys/identifiers. Malformed or excessively long keys could potentially cause unexpected behavior or buffer issues in the Keychain framework. Fix: Implement strict input validation for all keychain keys: enforce maximum length limits, validate character sets, and reject null/empty values before passing to Keychain APIs.
• Low · Potential Information Disclosure via Error Messages — Sources/KeychainSwift.swift, Demo/ViewController.swift. If error messages from Keychain operations are logged or exposed to users, they could reveal information about stored items or system state that could aid attackers in targeted attacks. Fix: Ensure error messages are generic and don't expose details about keychain item existence, types, or structure. Log detailed errors only in debug builds or secure logging systems.
• Low · Access Control Attribute Defaults Not Verified — Sources/KeychainSwiftAccessOptions.swift. The KeychainSwiftAccessOptions.swift file suggests configurable access control, but it's unclear if secure defaults (e.g., kSecAttrAccessibleWhenUnlockedThisDeviceOnly) are enforced when not explicitly specified. Fix: Verify that the library enforces kSecAttrAccessibleWhenUnlockedThisDeviceOnly as the default access control attribute. Document security implications of different access options in comments.
• Low · No Visible Data Encryption Configuration — Sources/KeychainSwift.swift. While Keychain provides encryption, the library doesn't show explicit configuration for encryption algorithms or key derivation parameters, relying entirely on system defaults. Fix: Document that the library relies on iOS/macOS system Keychain encryption. Consider adding comments explaining the security guarantees provided by the underlying Keychain framework.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.