CLI

واجهة سطر أوامر OpenKey (openkey) مخصّصة للمطوّرين الذين يحفظون الأسرار ورموز API ومفاتيح SSH ومواد .env في خزنة OpenKey. يمكنها العمل دون اتصال بالكامل لتوليد كلمات المرور، والتواصل مع تطبيق OpenKey لسطح المكتب وهو مفتوح القفل عبر جسر محلي، والمصادقة اختيارياً على خادم مزامنة مستضاف ذاتياً لسحب النص المشفّر وجلسة CLI قصيرة العمر.

يتطلب Node.js 20+.

البنية

الرسم أدناه يوضّح من يتحدث مع من. توليد كلمات المرور يبقى دون اتصال. أوامر الخزنة تفضّل تطبيق سطح المكتب المفتوح. مزامنة الخادم اختيارية.

الوضع	متى يُستخدم	ماذا يمكنه
دون اتصال	دائماً	gen — بلا تطبيق وبلا خادم
الجسر الأصلي	تطبيق سطح المكتب مفتوح القفل على هذا الجهاز	إدارة الأسرار، استيراد الاكتشاف، البحث/الجلب/النسخ عبر الأسرار وتسجيلات الدخول
جلسة CLI	بعد login ثم eval $(openkey unlock)	نفس عمليات الخزنة على ذاكرة نص مشفّر محلية؛ sync يسحب من الخادم

كيف يختار أمر الخزنة الخلفية

1. إن استجاب جسر سطح المكتب → وضع native (المفضّل؛ بلا تسجيل على الخادم).
2. وإلا إن وُجد OPENKEY_SESSION صالح → وضع session (الذاكرة المحلية / مواد مدعومة بالخادم).
3. وإلا → تفشل الأوامر التي تحتاج الخزنة مع تلميح لفتح قفل التطبيق أو تشغيل eval $(openkey unlock).

يقبل الجسر الاتصالات من الجهاز المحلي فقط وطالما الخزنة مفتوحة. على Unix يُستخدم مقبس تحت مسارات OpenKey المعروفة (تجاوز عبر OPENKEY_NATIVE_SOCKET). على Windows يُستخدم منفذ localhost من ملف تحت %LOCALAPPDATA%\OpenKey\ (تجاوز عبر OPENKEY_NATIVE_PORT).

التثبيت

cd openkey_cli
npm install
npm run build
npm link          # اختياري: يضع `openkey` في PATH

بدون الربط:

npx tsx src/cli.ts --help
# بعد البناء:
node dist/cli.js --help

تحقق:

openkey --version
openkey status

الإعداد والتخزين

تُحفظ حالة CLI المحلية في مجلد إعدادات المنصة (صلاحية الملف 600 عند الدعم):

المنصة	المسار
macOS	~/Library/Application Support/OpenKey/config.json
Linux	~/.config/openkey/config.json (أو $XDG_CONFIG_HOME/openkey/)
Windows	%APPDATA%\OpenKey\config.json

قد يحتوي الملف على: عنوان الخادم، البريد، رموز الوصول/التحديث، الملح ومعاملات KDF، مفتاح الخزنة الملفوف، مدة قفل الجلسة، رقم مراجعة الخادم، وذاكرة نص مشفّر للعناصر والمجموعات بعد المزامنة. لا يخزّن كلمة المرور الرئيسية بنص واضح.

أوامر config

openkey config set-server https://openkey.example.com
openkey config show
openkey config set-lock 30    # مدة الجلسة بالدقائق (1–1440، الافتراضي 15)

• set-server يتطلب عنواناً يبدأ بـ http:// أو https:// (يُزال الشرطة المائلة النهائية).
• العنوان الافتراضي قبل أول تعيين: http://localhost:8000.

الخيارات العامة

العلم	الأثر
--json	JSON قابل للقراءة آلياً على stdout للسكربتات
--help / --version	المساعدة والإصدار

ضع --json قبل الأمر الفرعي عند استخدام الخيارات العامة، مثل: openkey --json status.

توليد كلمات المرور (gen)

دون اتصال بالكامل. لا يحتاج التطبيق ولا الخادم.

openkey gen
openkey gen -l 24 --no-symbols
openkey gen -l 32 -a -c
openkey --json gen -l 20

الخيار	الوصف	الافتراضي
-l, --length <n>	الطول (نطاق عملي 4–64)	20
--no-upper	استبعاد الأحرف الكبيرة	معطّل
--no-lower	استبعاد الأحرف الصغيرة	معطّل
--no-digits	استبعاد الأرقام	معطّل
--no-symbols	استبعاد الرموز	معطّل
-a, --avoid-ambiguous	تجنّب الأحرف الملتبسة Il1O0o	معطّل
-c, --copy	نسخ إلى الحافظة بدل الطباعة	معطّل

مع -c يطبع الوضع البشري تأكيداً؛ وضع JSON يعيد { "copied": true, "length": N }. بدون -c تُطبع كلمة المرور (أو { "password": "..." } في JSON).

الحالة والتنظيف

openkey status
openkey forget

status يعرض عنوان الخادم، البريد، حالة الدخول، توفّر الجسر، وضع الفتح (native / session)، الوقت المتبقي للجلسة، وعدد العناصر المخزّنة مؤقتاً.

forget يمسح إعدادات CLI المحلية وذاكرة النص المشفّر. لا يحذف الأسرار داخل خزنة تطبيق سطح المكتب. بعد forget أعد config set-server / login إن كنت تستخدم وضع الخادم.

أسرار المطوّرين (secret)

تعيش الأسرار في منطقة الأسرار المحجوزة في الخزنة (__dev_secrets__)، مجمّعة حسب الجهاز (تسمية الآلة؛ اسم المضيف افتراضياً). تتطلب الأوامر تطبيق سطح المكتب مفتوح القفل أو OPENKEY_SESSION صالحاً.

الأنواع

النوع	الاستخدام النموذجي	ملاحظات
apiToken	PAT ومفاتيح API	الافتراضي
sshKey	مفاتيح خاصة	يُفضَّل --file / --public-key-file
envSnippet	محتوى .env كامل	يُفضَّل --file
other	عام	—

تُطبَّع أسماء مستعارة مثل ssh وapi وtoken وenv و.env إلى الأنواع أعلاه.

secret add

openkey secret add --name "GitHub PAT" --kind apiToken --secret ghp_...
openkey secret add -n "deploy key" -k sshKey -f ~/.ssh/id_ed25519 \
  --public-key-file ~/.ssh/id_ed25519.pub -H git.example.com -u git
openkey secret add -n "acme .env" -k envSnippet -f ./apps/api/.env -d laptop

الخيار	الوصف
-n, --name	الاسم المعروض (مطلوب)
-k, --kind	sshKey | apiToken | envSnippet | other
-s, --secret	قيمة السر مباشرة
-f, --file	قراءة جسم السر من ملف
-u, --username	اسم مستخدم اختياري
-H, --host	مضيف اختياري
-d, --device	تسمية مجموعة الجهاز (الافتراضي: اسم المضيف)
--public-key / --public-key-file	المفتاح العام لـ SSH
--passphrase	عبارة مرور المفتاح
--notes	ملاحظات حرة

وفّر --secret أو --file (غير فارغ). تُرجع السجلات المُنشأة معرّف UUID.

secret list / get / copy / rm

openkey secret list
openkey secret get "GitHub"
openkey secret copy ghp
openkey secret rm "old token" -y

• list — جدول لبادئة UUID والاسم والنوع والجهاز والسر المقنّع.
• get / copy / rm — مطابقة بالـاسم أو الـمضيف أو بادئة UUID. التطابق الغامض يُخطئ ويعرض المرشحين؛ ضيّق الاستعلام.
• get يطبع النص الصريح (أو كائن JSON كاملاً مع --json).
• copy يكتب النص الصريح إلى الحافظة.
• rm يطلب تأكيداً ما لم تُمرَّر -y / --yes.

الاكتشاف (discover)

يمسح هذا الجهاز ويستورد الأسرار الجديدة إلى مجموعة الجهاز. يزيل التكرار مقابل القيم الموجودة في الخزنة (حسب النوع + الاسم + بصمة المحتوى).

openkey discover --dry-run
openkey discover -y
openkey discover -d workstation -p ~/src/acme -p ~/src/labs --depth 3
openkey discover --no-aws --no-env-vars

الخيار	الوصف	الافتراضي
-d, --device	اسم مجموعة الجهاز	اسم المضيف
-p, --path <dir>	جذر/جذور المشاريع لمسح .env (قابل للتكرار)	المجلد الحالي
--depth <n>	أقصى عمق للمجلدات لـ .env	4
--no-ssh	تخطّي المفاتيح الخاصة في ~/.ssh	المسح مفعّل
--no-env-files	تخطّي ملفات .env / .env.*	المسح مفعّل
--no-env-vars	تخطّي متغيرات بيئة العملية	المسح مفعّل
--no-aws	تخطّي ~/.aws/credentials	المسح مفعّل
--dry-run	سرد فقط دون حفظ	معطّل
-y, --yes	استيراد بلا تأكيد تفاعلي	معطّل

ما الذي يُمسح؟

• SSH — مفاتيح خاصة تحت ~/.ssh (يتخطى known_hosts وauthorized_keys وconfig وملفات .pub)؛ يرفق ملف .pub الشقيق عند وجوده.
• متغيرات البيئة — أسماء معروفة (GITHUB_TOKEN، OPENAI_API_KEY، DATABASE_URL، …) وأسماء تطابق لواحق شبيهة بالأسرار؛ يتخطى PATH وHOME وOPENKEY_SESSION وOPENKEY_PASSWORD وغيرها.
• AWS — ملفات التعريف في ~/.aws/credentials.
• ملفات .env — مشي من الجذور مع تخطّي node_modules و.git وdist والبيئات الافتراضية وغيرها؛ تُطبَّق حدود للحجم وعدد الملفات.

يعمل --dry-run حتى لو كانت الخزنة مقفلة (سرد فقط). الحفظ يتطلب فتح الجسر أو الجلسة. الأسرار المستوردة مسبقاً تُبلَّغ كمتجاوَزة.

البحث عبر الأسرار وتسجيلات الدخول

تبحث هذه الأوامر في أسرار المطوّرين وتسجيلات الدخول:

openkey search github
openkey get "GitHub"
openkey copy api.example.com

الأمر	المخرجات
search <query>	جدول مقنّع (أو معاينات JSON)
get <query>	كلمة المرور/السر للنتيجة الأفضل
copy <query>	نسخ أفضل تطابق إلى الحافظة

التطابق الغامض يعرض UUID والنوع والتسمية — ضيّق الاستعلام. فضّل secret get / secret copy عندما تريد قسم الأسرار فقط.

خادم مستضاف ذاتياً (اختياري)

استخدم هذا المسار عندما لا يتوفر تطبيق سطح المكتب على الجهاز (مثلاً خزنة على الهاتف عبر المزامنة فقط)، أو عندما تريد ذاكرة نص مشفّر لـ CLI.

openkey config set-server http://localhost:8000
openkey login --email [email protected]
eval $(openkey unlock)
openkey sync

تثبيت الخادم: تثبيت الخادم.

تدفق المصادقة

1. login — يطلب البريد (أو -e) وكلمة المرور الرئيسية (أو OPENKEY_PASSWORD). ينفّذ prelogin للملح وKDF، يشتق auth_hash بـ Argon2id، يحصل على JWT، يجلب مادة مفتاح الخزنة الملفوف، يتحقق من كلمة المرور بفك الالتفاف، ثم يسحب النص المشفّر إلى الذاكرة المحلية. لا ترسل كلمة المرور الرئيسية كعلم CLI.
2. unlock — يشتق مفتاح الخزنة مجدداً، يحدّث الرموز/المزامنة عند توفّر الخادم، ويطبع أمر تصدير للقشرة لـ OPENKEY_SESSION (استخدم eval $(openkey unlock)). خيارات: -e/--email، --raw (الرمز فقط). وضع JSON يُخرج حقول الجلسة.
3. lock — يطبع unset OPENKEY_SESSION (أو تلميح JSON) لتنفيذ eval $(openkey lock).
4. logout — يمسح رموز الوصول/التحديث؛ يُبقي ذاكرة النص المشفّر المحلية. اقرنه بـ lock لمسح متغير الجلسة.
5. sync — يتطلب دخولاً؛ يسحب العناصر/المجموعات ويحدّث serverRevision.

مدة الجلسة الافتراضية 15 دقيقة (config set-lock). الجلسات المنتهية تتطلب unlock مجدداً.

متغيرات البيئة

المتغير	الغرض
OPENKEY_SESSION	كتلة جلسة مشفّرة قصيرة العمر من unlock
OPENKEY_PASSWORD	كلمة المرور الرئيسية لـ login / unlock غير التفاعلي (سكربتات/CI فقط)
OPENKEY_NATIVE_SOCKET	تجاوز مسار مقبس الجسر على Unix
OPENKEY_NATIVE_PORT	تجاوز منفذ الجسر على Windows

فضّل المطالبة التفاعلية بكلمة المرور على أجهزتك الشخصية. عامل OPENKEY_PASSWORD ورموز الجلسة كمادة سرية في سجلات CI.

مرجع الأوامر

الأمر	يحتاج وصولاً للخزنة؟	الوصف
gen	لا	توليد كلمة مرور دون اتصال
discover	الحفظ: نعم* / dry-run: لا	مسح SSH / .env / البيئة / AWS ← مجموعة الجهاز
secret add|list|get|copy|rm	نعم*	أسرار المطوّرين
get / copy / search	نعم*	أسرار + تسجيلات دخول
status	لا	حالة الجسر / الجلسة / الخادم
config set-server|show|set-lock	لا	إعداد CLI
login / logout	—	مصادقة خادم اختيارية
unlock / lock	—	جلسة CLI اختيارية
sync	يتطلب دخولاً	سحب النص المشفّر من الخادم
forget	لا	مسح إعدادات وذاكرة CLI المحلية

*تطبيق سطح المكتب مفتوح القفل، أو OPENKEY_SESSION صالح بعد دخول الخادم.

نموذج الأمان

• أوامر السرد/البحث تقنّع القيم؛ استخدم get / copy فقط عند الحاجة للنص الصريح.
• خادم المزامنة يخزّن نصاً مشفّراً فقط؛ يشتق CLI المفاتيح محلياً كسائر عملاء OpenKey.
• لا تمرّر كلمة المرور الرئيسية كعلم؛ تجنّب تسجيل OPENKEY_PASSWORD أو OPENKEY_SESSION.
• حركة الجسر محلية فقط وتتطلب خزنة مفتوحة.
• تنتهي رموز الجلسة؛ قلّل المدة بـ config set-lock على الأجهزة المشتركة.
• forget يمسح حالة CLI على القرص؛ أدر رموز الخادم بـ logout إن أصبح الجهاز غير موثوق لاحقاً.

التطوير

cd openkey_cli
npm test
npm run typecheck
npm run build

أدلة ذات صلة

• استخدام التطبيق — فتح سطح المكتب، قسم الأسرار، التعبئة التلقائية
• تثبيت الخادم — مزامنة مستضافة ذاتياً
• الأمان — Argon2id والرموز ونموذج التهديد
• الحزم — تخطيط المستودع