KeychainAccess Swift: طرق، أمثلة، تثبيت

ما هي KeychainAccess ولماذا تحتاجها؟

KeychainAccess هي مكتبة خفيفة وقوية للغة Swift توفر واجهة سهلة وآمنة من حيث النوع للتعامل مع Keychain Services (سلسلة المفاتيح) من Apple. Keychain هو مخزن آمن مدمج في أنظمة iOS، macOS، watchOS و tvOS، مصمم لتخزين البيانات الحساسة: كلمات المرور، مفاتيح التشفير، رموز المصادقة، أرقام بطاقات الائتمان وأي معلومات سرية أخرى.

بدون المكتبات، العمل مع Keychain عبر واجهة C الأصلية (دوال SecItemAdd، SecItemCopyMatching، SecItemUpdate، SecItemDelete) مرهق للغاية، ويتطلب كتابة الكثير من الكود المتكرر ويكون عرضة للأخطاء. KeychainAccess تحل هذه المشكلة من خلال تقديم:

صياغة Swift بسيطة: العمل عبر الخصائص (get/set) والطرق بأسماء واضحة.
أمان من حيث النوع: يتم تحويل البيانات تلقائياً إلى String أو Data أو أنواع مخصصة تطبق Codable.
مرونة: دعم مستويات وصول مختلفة (متاح للتطبيق، بعد فتح الجهاز، مع القياسات الحيوية)، والعمل مع مجموعات Keychain ومزامنة iCloud.
أمان افتراضي: تستخدم المكتبة أفضل ممارسات الأمان الموصى بها من Apple.

المكتبة مثالية لتخزين رموز OAuth، كلمات مرور المستخدمين، مفاتيح API، عبارات البذور للمحافظ الرقمية وأي بيانات أخرى لا يمكن تخزينها في UserDefaults أو في نظام الملفات بشكل مفتوح.

تثبيت KeychainAccess

KeychainAccess لا يتم تثبيتها عبر pip (Python) أو npm (JavaScript). إنها مكتبة أصلية لنظام Apple البيئي. الطرق الرئيسية للتثبيت:

1. Swift Package Manager (SPM) — الطريقة الموصى بها

في Xcode: File → Add Packages... → الصق رابط المستودع:

https://github.com/kishikawakatsumi/KeychainAccess.git

اختر الإصدار (عادةً "Up to Next Major" مع آخر إصدار مستقر) وأضف الحزمة إلى الـ target الخاص بك.

أو أضف التبعية في ملف Package.swift الخاص بحزمتك:

// swift-tools-version:5.7
import PackageDescription

let package = Package(
    name: "MyPackage",
    dependencies: [
        .package(url: "https://github.com/kishikawakatsumi/KeychainAccess.git", from: "4.2.2")
    ],
    targets: [
        .target(
            name: "MyPackage",
            dependencies: ["KeychainAccess"]),
    ]
)

2. CocoaPods

أضف السطر التالي إلى ملف Podfile الخاص بك:

pod 'KeychainAccess'

ثم نفذ الأمر pod install.

3. Carthage

أضف إلى ملف Cartfile:

github "kishikawakatsumi/KeychainAccess"

ثم نفذ الأمر carthage update وأضف الإطار (framework) إلى مشروعك.

بداية سريعة مع KeychainAccess

بعد التثبيت، قم باستيراد المكتبة: import KeychainAccess

أبسط مثال هو حفظ وقراءة نص:

import KeychainAccess

// إنشاء كائن للعمل مع Keychain الخاص بالتطبيق
let keychain = Keychain(service: "com.example.myapp")

// حفظ قيمة
try keychain.set("my_secret_password", key: "user_password")

// قراءة قيمة
if let password = try keychain.get("user_password") {
    print("كلمة المرور الموجودة: \(password)")
} else {
    print("لم يتم العثور على كلمة المرور")
}

// حذف قيمة
try keychain.remove("user_password")

هذا الكود يقوم بثلاث عمليات أساسية: الكتابة، القراءة والحذف. لاحظ معالجة الأخطاء باستخدام try — عمليات Keychain قد ترمي استثناءات (مثلاً عند مشاكل في الوصول أو عدم وجود صلاحيات).