envsec

إدارة آمنة للأسرار البيئية باستخدام مخازن بيانات نظام التشغيل الأصلية.

عرض توضيحي

الميزات

• تخزين الأسرار في مخزن بيانات نظام التشغيل الأصلي (وليس ملفات نصية عادية)
• متعدد المنصات: macOS، Linux، Windows
• تنظيم الأسرار حسب السياق (مثل myapp.dev، stripe-api.prod، work.staging)
• تتبع بيانات وصفية للأسرار (أسماء المفاتيح، الطوابع الزمنية) عبر SQLite
• البحث في السياقات والأسرار باستخدام أنماط glob
• تشغيل الأوامر مع استيفاء الأسرار
• حفظ وإعادة تشغيل الأوامر باستخدام cmd (بحث، قائمة، تشغيل، حذف)
• تصدير الأسرار إلى ملفات .env (مع تتبع الأجيال عبر audit)
• تصدير الأسرار كمتغيرات بيئة للقشرة (eval $(envsec env))
• تحميل الأسرار من ملفات .env (مع اكتشاف التعارضات)
• مشاركة الأسرار مشفرة باستخدام GPG لأعضاء الفريق
• واجهة طرفية تفاعلية (envsec tui) لإدارة الأسرار دون حفظ الأوامر

الحزم

هذا مستودع أحادي يحتوي على الحزم التالية:

الحزمة	الوصف	npm
envsec	أداة سطر الأوامر لإدارة الأسرار
@envsec/sdk	SDK لـ Node.js / Bun لتحميل الأسرار برمجيًا
@envsec/core	المحرك الأساسي — محولات مخزن بيانات نظام التشغيل + قاعدة بيانات البيانات الوصفية
@envsec/tui	واجهة طرفية تفاعلية لإدارة الأسرار

بدء سريع لـ SDK

للوصول البرمجي إلى الأسرار من Node.js أو Bun، استخدم @envsec/sdk:```bash npm install @envsec/sdk

بعد اكتمال التثبيت، يمكنك التحقق من التثبيت عن طريق تشغيل الأمر التالي:

```bash
toolname --version

يجب أن يظهر إصدار الأداة في الإخراج. إذا واجهت أي أخطاء، فتأكد من تثبيت جميع المتطلبات الأساسية بشكل صحيح.

الاستخدام

لاستخدام الأداة، اتبع الخطوات التالية:

1. افتح الطرفية (Terminal) أو موجه الأوامر (Command Prompt).
2. انتقل إلى الدليل الذي قمت بتثبيت الأداة فيه.
3. قم بتشغيل الأمر التالي:

toolname [options] <target>

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

أمثلة

فيما يلي بعض الأمثلة على كيفية استخدام الأداة:

# فحص هدف أساسي
toolname example.com

# فحص مع إخراج مفصل
toolname -v example.com

# حفظ النتائج في ملف
toolname -o results.txt example.com

# تعيين مهلة زمنية مخصصة
toolname -t 60 example.com

التكوين

يمكن تكوين الأداة عبر ملف إعدادات يقع في المسار التالي:

~/.config/toolname/config.yaml

إذا لم يكن الملف موجودًا، يمكنك إنشاؤه يدويًا. فيما يلي مثال على بنية ملف الإعدادات:

# إعدادات الأداة
timeout: 30
threads: 10
user_agent: "Mozilla/5.0 (compatible; ToolName/1.0)"
proxy: ""

شرح الإعدادات

• timeout: المهلة الزمنية الافتراضية بالثواني لكل طلب.
• threads: عدد الخيوط المتزامنة المستخدمة أثناء الفحص.
• user_agent: سلسلة وكيل المستخدم المرسلة في الطلبات.
• proxy: عنوان الخادم الوكيل (اختياري). اتركه فارغًا لتعطيل الوكيل.

استكشاف الأخطاء وإصلاحها

مشكلة: "الأمر غير موجود" عند تشغيل الأداة

الحل: تأكد من أن مسار التثبيت مضاف إلى متغير البيئة PATH. يمكنك التحقق من ذلك عن طريق تشغيل:

echo $PATH

إذا لم يكن المسار موجودًا، أضفه يدويًا:

export PATH=$PATH:/path/to/toolname/bin

مشكلة: خطأ في الاتصال بالشبكة

الحل: تحقق من اتصال الإنترنت لديك، وتأكد من أن جدار الحماية لا يحظر الاتصالات الصادرة. إذا كنت تستخدم وكيلًا، فتأكد من ضبط إعدادات الوكيل بشكل صحيح في ملف التكوين.

مشكلة: نتائج غير متوقعة

الحل: قم بتشغيل الأداة مع خيار -v للحصول على إخراج مفصل، مما يساعد في تحديد مصدر المشكلة. يمكنك أيضًا التحقق من سجلات الأداة في الدليل التالي:

~/.local/share/toolname/logs/

المساهمة

نرحب بالمساهمات في تطوير هذه الأداة! إذا كنت ترغب في المساهمة، يرجى اتباع الخطوات التالية:

1. قم بعمل Fork للمستودع.
2. أنشئ فرعًا جديدًا للميزة أو الإصلاح الخاص بك.
3. قم بإجراء التغييرات اللازمة.
4. تأكد من اجتياز جميع الاختبارات.
5. أرسل طلب سحب (Pull Request) مع وصف واضح للتغييرات.

الترخيص

هذه الأداة مرخصة بموجب رخصة MIT. راجع ملف LICENSE للحصول على التفاصيل الكاملة.

الإسناد

تم تطوير هذه الأداة بواسطة اسم المطور مع مساهمات من مجتمع المصادر المفتوحة. شكر خاص لجميع المساهمين الذين ساعدوا في تحسين هذه الأداة.

لمزيد من المعلومات، يرجى زيارة صفحة المشروع أو الانضمام إلى خادم الديسكورد الخاص بنا.```typescript import { loadSecrets } from "@envsec/sdk";

// Load and inject into process.env await loadSecrets({ context: "myapp.dev", inject: true });

// Or use the client for full control import { EnvsecClient } from "@envsec/sdk"; const client = await EnvsecClient.create({ context: "myapp.dev" }); const apiKey = await client.get("api.key"); await client.close();

انظر إلى [وثائق SDK الكاملة](https://github.com/davidnussio/envsec/blob/main/packages/sdk/README.md) لجميع واجهات برمجة التطبيقات، ودعم السياقات المتعددة، والخيارات.

## المتطلبات

- Node.js >= 22

### macOS

لا توجد تبعيات إضافية. يستخدم Keychain المدمج عبر أداة سطر الأوامر `security`.

### Linux

يتطلب `libsecret-tools` (الذي يوفر أمر `secret-tool`)، والذي يتواصل مع GNOME Keyring أو KDE Wallet أو أي مزود خدمة Secret Service عبر D-Bus.```bash
# Debian / Ubuntu
sudo apt install libsecret-tools

# Fedora
sudo dnf install libsecret

# Arch
sudo pacman -S libsecret

يجب أن تكون جلسة D-Bus قيد التشغيل وخدمة keyring (مثل gnome-keyring-daemon) نشطة. معظم بيئات سطح المكتب تتعامل مع هذا تلقائيًا.

Windows

لا توجد تبعيات إضافية. يستخدم Windows Credential Manager المدمج عبر cmdkey وPowerShell.

التثبيت

Homebrew (macOS / Linux)```bash

brew tap davidnussio/homebrew-tap brew install envsec

### npm```bash
npm install -g envsec

npx (بدون تثبيت)```bash

npx envsec

### mise```bash
mise use -g npm:envsec

الاستخدام

تتطلب معظم الأوامر تحديد سياق باستخدام --context (أو -c). السياق هو تسمية حرة لتجميع الأسرار — على سبيل المثال myapp.dev، stripe-api.prod، work.staging.

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

هذه الخيارات متاحة على جميع الأوامر:

• --context, -c — اسم السياق (مثل myapp.dev، stripe-api.prod). يقرأ أيضًا متغير البيئة ENVSEC_CONTEXT
• --debug, -d — تفعيل تسجيل التصحيح
• --json — الإخراج بتنسيق JSON للبرمجة النصية
• --db — مسار ملف قاعدة بيانات SQLite (الافتراضي: ~/.envsec/store.sqlite). يقرأ أيضًا متغير البيئة ENVSEC_DB

مسار قاعدة بيانات مخصص

افتراضيًا، يتم تخزين البيانات الوصفية في ~/.envsec/store.sqlite. يمكنك تجاوز ذلك باستخدام --db أو متغير البيئة ENVSEC_DB:```bash

Use a project-local database

envsec --db ./local-store.sqlite -c myapp.dev list

Or via environment variable

export ENVSEC_DB=/shared/team/envsec.sqlite envsec -c myapp.dev list

العلامة `--db` لها الأولوية على `ENVSEC_DB`. تشمل حالات الاستخدام قواعد بيانات خاصة بالمشروع، وقواعد بيانات مشتركة بين الفريق على محركات أقراص الشبكة، وCI/CD مع تخزين مؤقت.

### إضافة سرّ

قم بتخزين سرّ في مخزن بيانات الاعتماد الخاص بنظام التشغيل.

- `<key>` — اسم مفتاح السرّ (مثل `api.key`، `db.password`)
- `--value`، `-v` — القيمة المراد تخزينها (احذفها للحصول على موجه إدخال مقنّع تفاعلي)
- `--expires`، `-e` — مدة الانتهاء (مثل `30m`، `2h`، `7d`، `4w`، `3mo`، `1y`)```bash
# Store a value inline
envsec -c myapp.dev add api.key --value "sk-abc123"

# Or use the short alias
envsec -c myapp.dev add api.key -v "sk-abc123"

# Omit --value for an interactive masked prompt
envsec -c myapp.dev add api.key

# Set an expiry duration with --expires (-e)
envsec -c myapp.dev add api.key -v "sk-abc123" --expires 30d

# Supported duration units: m (minutes), h (hours), d (days), w (weeks), mo (months), y (years)
# Combinable: 1y6mo, 2w3d, 1d12h
envsec -c myapp.dev add api.key -v "sk-abc123" -e 6mo

الحصول على سر

استرجاع قيمة سر من مخزن بيانات الاعتماد الخاص بنظام التشغيل.

• <key> — اسم مفتاح السر المطلوب استرجاعه
• --quiet, -q — طباعة القيمة الخام فقط (بدون تحذيرات أو مخرجات إضافية)
• --json — الإخراج بتنسيق JSON (يتضمن السياق والمفتاح والقيمة و expires_at)```bash envsec -c myapp.dev get api.key

Print only the raw value (no warnings or extra output)

envsec -c myapp.dev get api.key --quiet envsec -c myapp.dev get api.key -q

### حذف سر

إزالة سر من مخزن بيانات الاعتماد في نظام التشغيل.

- `<key>` — اسم مفتاح السر المراد حذفه (اختياري إذا تم استخدام `--all`)
- `--yes`, `-y` — تخطي مطالبة التأكيد
- `--all` — حذف جميع الأسرار في السياق```bash
envsec -c myapp.dev delete api.key

# or use the alias
envsec -c myapp.dev del api.key

إعادة تسمية سر

إعادة تسمية مفتاح سر ضمن نفس السياق. يتم الحفاظ على القيمة وبيانات الانتهاء الوصفية.

• <old-key> — اسم مفتاح السر الحالي
• <new-key> — اسم مفتاح السر الجديد
• --force, -f — استبدال الهدف إذا كان موجودًا بالفعل```bash

Rename a key

envsec -c myapp.dev rename old.key new.key

Overwrite target if it already exists

envsec -c myapp.dev rename old.key existing.key --force

### سرد جميع الأسرار في سياق

سرد جميع مفاتيح الأسرار والبيانات الوصفية في سياق.

- `--json` — الإخراج بتنسيق JSON```bash
envsec -c myapp.dev list

سرد جميع السياقات

سرد جميع السياقات المتاحة مع عدد الأسرار.

• --json — الإخراج بتنسيق JSON```bash

Without --context, lists all available contexts with secret counts

envsec list

### البحث عن الأسرار

ابحث عن الأسرار أو السياقات باستخدام أنماط glob.

- `<pattern>` — نمط glob للبحث عنه (مثل `api.*`، `myapp.*`)
- `--json` — الإخراج بتنسيق JSON```bash
# Search secrets within a context
envsec -c myapp.dev search "api.*"

# Search contexts by pattern (without --context)
envsec search "myapp.*"

نقل الأسرار بين السياقات

انقل الأسرار من سياق إلى آخر. تتم إزالة الأسرار المصدرية بعد النقل.

• <pattern> — نمط Glob أو مفتاح محدد للنقل (اختياري إذا تم استخدام --all)
• --to, -t — السياق الهدف لنقل الأسرار إليه
• --all — نقل جميع الأسرار من السياق المصدر
• --force, -f — استبدال الأسرار الموجودة في السياق الهدف
• --yes, -y — تخطي رسالة التأكيد```bash

Move a single secret

envsec -c myapp.dev move api.token --to myapp.prod

Move secrets matching a glob pattern

envsec -c myapp.dev move "redis.*" --to myapp.prod -y

Move all secrets from one context to another

envsec -c myapp.dev move --all --to myapp.prod -y

Overwrite existing secrets in the target context

envsec -c myapp.dev move "redis.*" --to myapp.prod --force -y

### نسخ الأسرار بين السياقات

انسخ الأسرار من سياق إلى آخر. تبقى الأسرار المصدر سليمة.

- `<pattern>` — نمط Glob أو مفتاح محدد للنسخ (اختياري إذا تم استخدام `--all`)
- `--to`, `-t` — السياق الهدف لنسخ الأسرار إليه
- `--all` — نسخ جميع الأسرار من السياق المصدر
- `--force`, `-f` — استبدال الأسرار الموجودة في السياق الهدف
- `--yes`, `-y` — تخطي رسالة التأكيد```bash
# Copy a single secret
envsec -c myapp.dev copy api.token --to myapp.staging

# Copy secrets matching a glob pattern
envsec -c myapp.dev copy "redis.*" --to myapp.staging -y

# Copy all secrets from one context to another
envsec -c myapp.dev copy --all --to myapp.staging -y

# Overwrite existing secrets in the target context
envsec -c myapp.dev copy "redis.*" --to myapp.staging --force -y

تشغيل أمر مع الأسرار

نفّذ أمرًا مع إقحام قيم الأسرار عبر العناصر النائبة أو حقنها كمتغيرات بيئة.

• <command> — الأمر المطلوب تنفيذه. استخدم العناصر النائبة {key} لإقحام الأسرار
• --inject, -i — حقن جميع أسرار السياق كمتغيرات بيئة (KEY.NAME → KEY_NAME)
• --save, -s — حفظ هذا الأمر لاستخدامه لاحقًا
• --name, -n — اسم للأمر المحفوظ (يُطلب تفاعليًا إذا تم حذفه مع --save)```bash

Placeholders {key} are resolved with secret values before execution

envsec -c myapp.dev run 'curl {api.url} -H "Authorization: Bearer {api.token}"'

Any {dotted.key} in the command string is replaced with its value

envsec -c myapp.prod run 'psql {db.connection_string}'

Inject ALL context secrets as environment variables (KEY.NAME → KEY_NAME)

envsec -c myapp.dev run --inject 'node server.js' envsec -c myapp.dev run -i 'docker compose up'

Combine --inject with placeholders

envsec -c myapp.dev run --inject 'curl {api.url} -H "Authorization: Bearer $API_TOKEN"'

Save the command for later use with --save (-s) and --name (-n)

envsec -c myapp.dev run --save --name deploy 'kubectl apply -f - <<< {k8s.manifest}'

If you use --save without --name, you'll be prompted interactively

envsec -c myapp.dev run --save 'psql {db.connection_string}'

إذا كان أي عنصر نائب يشير إلى سر غير موجود، فلن يتم تنفيذ الأمر وسترى خطأً واضحًا:```
❌ Missing secrets in context "myapp.dev":
  - api.url
  - api.token

Add them with: envsec -c myapp.dev add <key>

الأوامر المحفوظة

تُخزَّن الأوامر المحفوظة تحت الأمر الفرعي cmd، مما يُبقيها منفصلة عن العمليات السرية.

cmd list

سرد جميع الأوامر المحفوظة.```bash envsec cmd list

#### cmd run

تشغيل أمر محفوظ (يستخدم السياق الذي تم حفظه به).

- `<name>` — اسم الأمر المحفوظ الذي سيتم تنفيذه
- `--override-context`, `-o` — تجاوز السياق المحفوظ في وقت التنفيذ
- `--quiet`, `-q` — كتم الإخراج المعلوماتي (طباعة مخرجات الأمر فقط)
- `--inject`, `-i` — حقن جميع أسرار السياق كمتغيرات بيئة```bash
envsec cmd run deploy

# Run quietly (suppress informational output like "Resolved N secret(s)")
envsec cmd run deploy --quiet
envsec cmd run deploy -q

# Override the context at execution time
envsec cmd run deploy --override-context myapp.prod
envsec cmd run deploy -o myapp.prod

# Inject all context secrets as env vars when running a saved command
envsec cmd run deploy --inject
envsec cmd run deploy -i

بحث cmd

ابحث في الأوامر المحفوظة حسب الاسم أو سلسلة الأوامر.

• <pattern> — نمط البحث
• --name, -n — البحث فقط في أسماء الأوامر
• --command, -m — البحث فقط في سلاسل الأوامر```bash envsec cmd search psql

Search only by name

envsec cmd search deploy -n

Search only by command string

envsec cmd search kubectl -m

#### cmd delete

احذف أمرًا محفوظًا.

- `<name>` — اسم الأمر المراد حذفه```bash
envsec cmd delete deploy

إنشاء ملف .env

قم بتصدير جميع الأسرار من سياق إلى ملف .env.

• --output, -o — مسار ملف الإخراج (الافتراضي: .env)```bash

Creates .env with all secrets from the context

envsec -c myapp.dev env-file

Specify a custom output path

envsec -c myapp.dev env-file --output .env.local

المفاتيح تُحوَّل إلى `UPPER_SNAKE_CASE` (مثل `api.token` ← `API_TOKEN`).

### تصدير الأسرار كمتغيرات بيئة

إخراج عبارات تصدير لاستخدامها مع `eval` أو تحميلها في الصدفة.

- `--shell`, `-s` — صيغة الصدفة المستهدفة: `bash` (الافتراضي)، `zsh`, `fish`, `powershell`
- `--unset`, `-u` — إخراج أوامر إلغاء التعيين/الإزالة بدلاً من التصدير```bash
# Output export statements for eval (bash/zsh)
eval $(envsec -c myapp.dev env)

# Specify target shell syntax
envsec -c myapp.dev env --shell fish
envsec -c myapp.dev env --shell powershell

# Output unset commands to clean up exported variables
eval $(envsec -c myapp.dev env --unset)

# Combine shell and unset
envsec -c myapp.dev env --unset --shell fish

الأصداف المدعومة: bash (الافتراضي)، zsh، fish، powershell. يتم تحويل المفاتيح إلى UPPER_SNAKE_CASE (مثل api.token → API_TOKEN). يذهب الإخراج إلى stdout بحيث يمكن تمريره إلى eval أو استيراده مباشرة — لا يُكتب أي ملف على القرص.

بدء جلسة صدفة بنطاق أسرار

قم بتشغيل صدفة فرعية تفاعلية مع حقن جميع الأسرار من السياق كمتغيرات بيئة. عند تنفيذ exit، تختفي الأسرار — لا حاجة للتنظيف.

• --shell، -s — الصدفة التي سيتم تشغيلها (bash، zsh، fish، powershell). الافتراضي: اكتشاف تلقائي
• --no-inherit — لا ترث متغيرات البيئة من الصدفة الأم
• --quiet، -q — إخفاء رسالة البدء/الخروج```bash envsec -c myapp.dev shell

I need the actual content of chunk 53 to translate it. Please provide the Markdown text you want translated.```
▶ envsec shell — context: myapp.dev (8 secrets loaded)
Type 'exit' or press Ctrl+D to leave the session.

(envsec:myapp.dev) ~ $ echo $DATABASE_URL
postgres://user:pass@localhost/mydb

(envsec:myapp.dev) ~ $ exit
→ Exiting envsec shell — secrets cleared.

بعد اكتمال التثبيت، يمكنك تشغيل الأداة باستخدام الأمر التالي:

python3 tool.py --help

خيارات سطر الأوامر

أمثلة الاستخدام

المسح الأساسي:

python3 tool.py -u https://example.com

المسح مع الإخراج التفصيلي وحفظ النتائج:

python3 tool.py -u https://example.com -v -o results.json -f json

استخدام وكيل لاعتراض الطلبات:

python3 tool.py -u https://example.com -p http://127.0.0.1:8080

المتطلبات

تعتمد الأداة على المكتبات التالية، والتي يتم تثبيتها تلقائيًا أثناء التثبيت:

• requests — للتعامل مع طلبات HTTP
• beautifulsoup4 — لتحليل محتوى HTML
• colorama — لتلوين مخرجات المحطة الطرفية
• urllib3 — لإدارة الاتصالات الأساسية

ملاحظة: إذا واجهت أي مشكلات في التثبيت، فتأكد من أنك تستخدم Python 3.8 أو إصدارًا أحدث، وأن pip محدث:

pip install --upgrade pip

استكشاف الأخطاء وإصلاحها

خطأ: "ModuleNotFoundError"

إذا ظهرت رسالة تفيد بعدم العثور على وحدة، فقم بتثبيت المتطلبات يدويًا:

pip install -r requirements.txt

خطأ: "Connection refused"

تأكد من أن الهدف متاح وأن جدار الحماية لا يحظر الاتصال. إذا كنت تستخدم وكيلًا، فتحقق من عنوانه ومنفذه.

خطأ: "Timeout"

قم بزيادة قيمة المهلة باستخدام الخيار -t:

python3 tool.py -u https://example.com -t 60

الترخيص

هذه الأداة مرخصة بموجب رخصة MIT. راجع ملف LICENSE للحصول على التفاصيل الكاملة.

إخلاء المسؤولية

تحذير: هذه الأداة مخصصة للأغراض التعليمية واختبار الاختراق الأخلاقي فقط. لا يجوز استخدامها ضد أنظمة لا تملك إذنًا صريحًا لاختبارها. يتحمل المستخدم المسؤولية الكاملة عن أي استخدام غير قانوني أو ضار لهذه الأداة.```bash

Force a specific shell

envsec -c myapp.dev shell --shell zsh

Only envsec secrets in env (no parent variables, except PATH)

envsec -c myapp.dev shell --no-inherit

Suppress the startup/exit banner

envsec -c myapp.dev shell --quiet

المتغير `ENVSEC_CONTEXT` يُضبط دائمًا داخل الجلسة، لذا يمكنك
الرجوع إليه في السكربتات أو تخصيصات المطالبة.

### تحميل الأسرار من ملف .env

استيراد الأسرار من ملف `.env` إلى سياق.

- `--input`, `-i` — مسار ملف الإدخال `.env` (الافتراضي: `.env`)
- `--force`, `-f` — استبدال الأسرار الموجودة دون مطالبة
- `--batch`, `-b` — وضع الدفعة: تأجيل حفظ قاعدة البيانات حتى يتم استيراد جميع الأسرار```bash
# Import secrets from .env into the context
envsec -c myapp.dev load

# Specify a custom input file
envsec -c myapp.dev load --input .env.local

# Overwrite existing secrets without warning
envsec -c myapp.dev load --force

يتم تحويل المفاتيح من UPPER_SNAKE_CASE إلى dotted.lowercase (مثال: API_TOKEN ← api.token). إذا كان المفتاح موجودًا بالفعل، يتم تخطيه مع تحذير ما لم يتم توفير --force (-f).

مشاركة الأسرار (مشفرة بـ GPG)

قم بتشفير جميع الأسرار من سياق معين لعضو فريق باستخدام GPG.

• --encrypt-to — مفتاح مستلم GPG (بريد إلكتروني، أو معرف مفتاح، أو بصمة إصبع) للتشفير له
• --output, -o — مسار ملف الإخراج (الافتراضي: stdout). استخدم - للإخراج إلى stdout بشكل صريح
• --json — استخدام تنسيق JSON داخل الحمولة المشفرة (الافتراضي: تنسيق .env)```bash

Encrypt all secrets from a context for a team member

envsec -c myapp.dev share --encrypt-to [email protected]

Save encrypted output to a file

envsec -c myapp.dev share --encrypt-to [email protected] -o secrets.enc

Use JSON format inside the encrypted payload

envsec -c myapp.dev --json share --encrypt-to [email protected] -o secrets.enc

المستلم يمكنه فك التشفير باستخدام `gpg --decrypt secrets.enc` وتوجيه الناتج إلى `envsec load`. بشكل افتراضي، يستخدم الحمولة المشفرة تنسيق `.env` (`KEY="value"`)؛ مع `--json` يستخدم كائن JSON منظم. يتطلب تثبيت GPG وأن يكون المفتاح العام للمستلم في سلسلة مفاتيحك.

### تدقيق الأسرار لانتهاء الصلاحية

تحقق من الأسرار المنتهية أو التي تنتهي صلاحيتها قريبًا، ومن تصديرات ملفات `.env` المتتبعة.

- `--within`, `-w` — عرض الأسرار التي تنتهي صلاحيتها خلال هذه المدة (الافتراضي: `30d`). استخدم `0d` لعرض الأسرار المنتهية صلاحيتها فقط
- `--json` — الإخراج بتنسيق JSON```bash
# Check for expired or expiring secrets in a context (default window: 30 days)
envsec -c myapp.dev audit

# Specify a custom window
envsec -c myapp.dev audit --within 7d

# Show only already-expired secrets
envsec -c myapp.dev audit --within 0d

# Audit across all contexts (omit --context)
envsec audit

# JSON output
envsec -c myapp.dev audit --json

الأسرار التي تم تعيين مدة انتهاء صلاحيتها --expires عبر envsec add يتم تتبعها في البيانات الوصفية. يقوم أمر audit بفحص الأسرار التي انتهت صلاحيتها بالفعل أو التي ستنتهي صلاحيتها خلال الفترة الزمنية المحددة. كما تعرض أمرا get وlist تحذيرات انتهاء الصلاحية بشكل مضمّن.

يقوم أمر audit أيضًا بتتبع ملفات .env المُنشأة. في كل مرة يتم فيها استخدام env-file، يتم تسجيل مسار الإخراج والسياق والطابع الزمني. يتضمن مخرَج التدقيق قسمًا ثانيًا يسرد هذه الملفات. إذا لم يعد ملف .env المُتتبَّع موجودًا على القرص، يقوم التدقيق تلقائيًا بإزالته من البيانات الوصفية ويُبلغ عن عملية التنظيف.

توليد سر عشوائي

قم بتوليد سر عشوائي آمن تشفيريًا، مع إمكانية تخزينه اختياريًا.

• <key> — اسم مفتاح السر (اختياري؛ احذفه لتوليد كلمة مرور مستقلة)
• --length, -l — طول السر المُولَّد (الافتراضي: 32)
• --prefix, -p — بادئة تُضاف إلى بداية السر المُولَّد (مثل sk_)
• --expires, -e — مدة انتهاء الصلاحية (مثل 30m, 2h, 7d, 4w, 3mo, 1y)
• --alphanumeric, -a — استخدام الأحرف الأبجدية الرقمية فقط [a-zA-Z0-9] (الافتراضي)
• --special, -s — تضمين الأحرف الخاصة الشائعة [a-zA-Z0-9!@#$%^&*]
• --all-chars, -A — استخدام جميع الأحرف القابلة للطباعة في ASCII لتحقيق أقصى قدر من العشوائية```bash

Generate and store a 32-char alphanumeric secret

envsec -c myapp.dev secret api.key

Custom length and prefix

envsec -c myapp.dev secret api.key --prefix "sk_" --length 48

Character sets:

--alphanumeric (-a) [a-zA-Z0-9] (default)

--special (-s) [a-zA-Z0-9] + !@#$%^&*

--all-chars (-A) all printable ASCII

envsec -c myapp.dev secret db.password --special --length 64

With expiry

envsec -c myapp.dev secret api.key --prefix "sk_" -l 48 --expires 90d

Standalone password generator (no store, just print)

envsec secret --length 32 envsec secret --special --length 64 --prefix "pk_"

عندما يتم توفير كل من السياق والمفتاح، يتم تخزين القيمة المُولّدة وطباعتها. وبدون أيٍّ منهما، تذهب القيمة الخام إلى stdout — وهو مفيد للتوجيه إلى `pbcopy` أو `xclip` أو أدوات أخرى.

### واجهة TUI تفاعلية

يتضمن envsec واجهة طرفية بملء الشاشة لإدارة الأسرار بشكل تفاعلي — دون الحاجة إلى حفظ الأوامر.```bash
# Launch the TUI
envsec tui

# Launch with a pre-selected context
envsec -c myapp.dev tui

توفر واجهة TUI ثماني شاشات يمكن الوصول إليها من القائمة الرئيسية:

• السياقات — تصفح جميع السياقات، تعيين السياق النشط باستخدام s، مسح السياق باستخدام x، عرض عدد الأسرار، حذف السياقات بالكامل
• الأسرار — عرض الأسرار في جدول، كشف القيم، إضافة أو حذف الأسرار
• إضافة سر — نموذج تفاعلي مع إدخال مقنّع ومدة انتهاء اختيارية
• البحث — بحث بنمط glob عبر الأسرار أو السياقات
• الأوامر المحفوظة — عرض، استعراض، وحذف قوالب الأوامر المحفوظة
• التدقيق — التحقق من الأسرار المنتهية أو القريبة من الانتهاء، مراجعة عمليات تصدير ملفات .env المتتبعة
• استيراد .env — تحميل الأسرار من ملف .env إلى السياق الحالي
• تصدير .env — تصدير الأسرار إلى ملف .env (متتبع للتدقيق)

اختصارات لوحة المفاتيح:

تشخيص إعداداتك

قم بتشغيل فحوصات الصحة للتحقق من تثبيت envsec لديك.

• --json — إخراج بتنسيق JSON للبرمجة النصية```bash

Run all health checks

envsec doctor

JSON output for scripting

envsec --json doctor

أمر `doctor` يتحقق من أن تثبيت envsec لديك يعمل بشكل صحيح. يتحقق من:
- دعم المنصة وإصدار Node.js
- توفر مخزن بيانات الاعتماد (Keychain في macOS، secret-tool في Linux، cmdkey في Windows)
- صلاحيات القراءة والكتابة لسلسلة المفاتيح
- مسار قاعدة البيانات، والأذونات، وسلامة المخطط
- الأسرار اليتيمة (بيانات وصفية بدون إدخال في سلسلة المفاتيح)
- الأسرار منتهية الصلاحية
- متغيرات البيئة (`ENVSEC_DB`، `ENVSEC_CONTEXT`)
- الصدفة الحالية

### إكمال الأوامر في الصدفة

يدعم envsec إكمال الأوامر بالضغط على Tab بشكل ديناميكي لكل من bash وzsh وfish. الإكمالات واعية بالسياق: فهي تقترح أسماء السياقات الفعلية لديك، ومفاتيح الأسرار، وأسماء الأوامر المحفوظة في الوقت الفعلي من خلال الاستعلام عن قاعدة البيانات الوصفية.```bash
# Bash (add to ~/.bashrc)
eval "$(envsec --completions bash)"

# Zsh (add to ~/.zshrc)
eval "$(envsec --completions zsh)"

# Fish (add to ~/.config/fish/config.fish)
envsec --completions fish | source

ما الذي يُكتمل ديناميكيًا:

• --context / -c — يسرد جميع سياقاتك
• وسيطات المفتاح السري (get, add, delete) — يسرد المفاتيح للسياق الحالي
• cmd run / cmd delete — يسرد أسماء الأوامر المحفوظة
• --override-context / -o — يسرد السياقات لـ cmd run
• الأوامر الفرعية، والأعلام، والخيارات الثابتة (الصدفات، وما إلى ذلك) تُكتمل أيضًا

المقارنة

كيف يقارن envsec بالأدوات الأخرى لإدارة أسرار البيئة؟

| المصادقة البيومترية | يرث القياسات الحيوية لنظام التشغيل (مثل فتح Keychain في macOS) | لا شيء | بصمة الإصبع / Touch ID عبر تكامل التطبيق | | تتبع البيانات الوصفية | SQLite (أسماء المفاتيح، الطوابع الزمنية — القيم أبدًا) | لا شيء | سجل عناصر وتدقيق قائم على السحابة |

باختصار: dotenv هو النهج الأبسط (ملفات على القرص)، و1Password CLI هو الأكثر غنىً بالميزات للفرق مع مزامنة سحابية وRBAC، وenvsec يقع في المنتصف — يقدم تشفيرًا أصليًا لنظام التشغيل بدون حسابات، وبدون تبعيات سحابية، وسير عمل موجه للمطورين يتجاوز ما يمكن لملفات .env فعله.

كيف يعمل

تُخزَّن الأسرار في مخزن بيانات الاعتماد الأصلي لنظام التشغيل. يُحدد الخلفية تلقائيًا بناءً على المنصة:

تُحفظ البيانات الوصفية (أسماء المفاتيح، الطوابع الزمنية) في قاعدة بيانات SQLite في ~/.envsec/store.sqlite (قابلة للتكوين عبر --db أو ENVSEC_DB). يجب أن تحتوي المفاتيح على فاصل نقطة واحد على الأقل (مثل service.account) والذي يُرسم إلى بنية الخدمة/الحساب في مخزن بيانات الاعتماد.

الأمان

بُني envsec حول مبدأ بسيط: أسرارك تنتمي إلى نظام التشغيل الخاص بك، وليس إلى ملفات dotfiles. كل قرار تصميمي يبدأ من هذا الأساس.

كيف يحمي envsec أسرارك

تشفير أصلي لنظام التشغيل، بدون تشفير مخصص. تُخزَّن قيم الأسرار مباشرة في macOS Keychain، أو GNOME Keyring / KDE Wallet، أو Windows Credential Manager. لا يخترع envsec تشفيره الخاص أبدًا — بل يفوض إلى مخازن بيانات الاعتماد المجرَّبة التي يوفرها نظام التشغيل بالفعل، محمية بجلسة المستخدم الخاصة بك و(على macOS) keychain تسجيل الدخول.

دعم Unicode كامل. يمكن أن تحتوي قيم الأسرار على أي أحرف Unicode، بما في ذلك الرموز التعبيرية والحروف المشكَّلة. تُرمَّز القيم بـ base64 قبل تخزينها في مخزن بيانات الاعتماد لنظام التشغيل، لتجنب غرابة الترميز الخاصة بالمنصة (مثل ترميز security CLI في macOS للمخرجات غير ASCII بالنظام السداسي العشري). تُقرأ الأسرار النصية القديمة بشفافية للتوافق مع الإصدارات السابقة.

الأسرار لا تلمس القرص كنص عادي أبدًا. تنتقل القيم مباشرة من الطرفية إلى مخزن بيانات الاعتماد لنظام التشغيل. لا تُكتب أبدًا إلى ملفات الإعدادات أو السجلات أو التخزين الوسيط.

لا أسرار في مخرجات الطرفية. تعرض أوامر list و search أسماء المفاتيح فقط — لا تُطبع القيم أبدًا. هذا يبقي الأسرار بعيدة عن مخازن التمرير، وتسجيلات الشاشة، ونطاق النظر من فوق الكتف.

تنفيذ أوامر آمن. يحقن أمر run الأسرار كمتغيرات بيئة للعملية الفرعية بدلاً من استيفائها في سلسلة الأوامر. هذا يعني أن قيم الأسرار لا تظهر في مخرجات ps أو سجل الصدفة. إذا كان أي سر مرجعي مفقودًا، يُحظر الأمر بالكامل — لا تنفيذ جزئي ببيانات اعتماد ناقصة.

التحقق من المدخلات ومنع الحقن. تُتحقق أسماء السياقات مقابل قائمة سماح صارمة (أحرف أبجدية رقمية، نقاط، شرطات، شرطات سفلية) مع فحوصات لعبور المسار وحقن النموذج الأولي. تستخدم جميع استعلامات SQLite عبارات مُعدَّة مع معاملات ربط، لمنع حقن SQL. تُهرب وسيطات PowerShell على Windows للحماية من حقن الأوامر.

أذونات ملفات مقيدة. يُنشأ دليل البيانات الوصفية (~/.envsec/) بأذونات 0700 وقاعدة بيانات SQLite بأذونات 0600، مما يحد من الوصول إلى المستخدم المالك.

القيود المعروفة ومجالات التحسين

نؤمن بالصراحة بشأن ما لا يغطيه envsec بعد. هذه مقايضات حقيقية، وليست أخطاء — وفهمها يساعدك على اتخاذ قرارات مستنيرة.

البيانات الوصفية مرئية. تخزن قاعدة بيانات SQLite في ~/.envsec/store.sqlite أسماء المفاتيح وأسماء السياقات والطوابع الزمنية — قيم الأسرار أبدًا، لكنها كافية للكشف عن ما الأسرار الموجودة. تُخزن أيضًا قوالب الأوامر المحفوظة (مع عناصر نائبة {key}) هناك. إذا كانت سرية البيانات الوصفية مهمة لك، فتأكد من أن دليل منزلك على وحدة تخزين مشفرة.

تصديرات env-file نصية عادية. يكتب أمر env-file قيم الأسرار إلى ملف .env على القرص. هذا حساس بطبيعته — عالج ملف الإخراج وفقًا لذلك ولا تلتزم به أبدًا في التحكم بالإصدارات. اعتبره جسرًا للراحة، وليس آلية تخزين.

تنفيذ الصدفة يحمل مخاطر متأصلة. يمرر أمر run قالب الأمر الخاص بك عبر /bin/sh (أو cmd.exe على Windows). إذا جاء القالب نفسه من مدخلات غير موثوقة، فحقن الصدفة ممكن. شغّل فقط قوالب الأوامر التي كتبتها أو تثق بها.

لا تحكم وصول عبر السياقات. يمكن لأي عملية تعمل كمستخدم نظام التشغيل الخاص بك قراءة جميع الأسرار عبر جميع السياقات. يعتمد envsec على عزل المستخدم على مستوى نظام التشغيل — لا يضيف طبقة تفويض خاصة به بين السياقات.

بيئات Linux بدون واجهة رسومية. على Linux، يعتمد envsec على جلسة D-Bus نشطة وبرنامج keyring خفي (مثل gnome-keyring-daemon). في الحاويات أو الخوادم بدون جلسة رسومية، قد يكون keyring غير متاح أو قد يخزن الأسرار بحماية أضعف.

التشفير يعتمد على نظام التشغيل الخاص بك. لا يضيف envsec أي تشفير إضافي عند التخزين يتجاوز ما يوفره مخزن بيانات الاعتماد الأصلي. على الأنظمة بدون تشفير كامل للقرص، يمكن لمهاجم بوصول مادي استخراج الأسرار من keychain. نوصي بتمكين تشفير القرص الكامل (FileVault، LUKS، BitLocker) لأقوى حماية.

التطوير

المتطلبات الأساسية

• Node.js >= 22
• pnpm

تستخدم حزم core و SDK و CLI و TUI Effect 4 وهي مثبتة حاليًا على 4.0.0-rc.112. حافظ على محاذاة إصدارات Effect و @effect/platform-node عبر مساحة العمل بينما يظل Effect 4 في حالة إصدار مرشح.

الإعداد```bash

git clone https://github.com/davidnussio/envsec.git cd envsec pnpm install pnpm run build

### بنية المشروع```
packages/
  cli/     → envsec CLI (published as `envsec`)
  sdk/     → Node.js/Bun SDK (published as `@envsec/sdk`)
  core/    → Core engine, shared by CLI and SDK (published as `@envsec/core`)
  tui/     → Interactive terminal UI (published as `@envsec/tui`)
apps/
  website/ → Documentation website

الأوامر الشائعة```bash

Build all packages

pnpm run build

Lint and format check (all packages)

pnpm run check

Auto-fix lint and formatting

pnpm run fix

Run package unit and contract tests

pnpm run test:unit

Run the CLI end-to-end suite with isolated database and credential fixtures

pnpm --filter envsec test

Release (build + changeset publish)

pnpm run release

مجموعة اختبارات E2E المعزولة لا تصل أبدًا إلى مخزن بيانات الاعتماد الأصلي. لتشغيل
محول نظام التشغيل الفعلي على macOS أو Linux، قم بالبناء أولاً ثم اختر الاشتراك صراحةً:```bash
ENVSEC_E2E_CLI="$PWD/packages/cli/dist/main.js" \
  ENVSEC_E2E_ISOLATED=0 \
  pnpm --filter envsec test

اختبارات E2E الأصلية تستخدم سياقات test.e2e* مخصصة وتقوم بإزالتها بعد ذلك.

التشغيل محليًا دون تثبيت

أنشئ اسمًا مستعارًا مؤقتًا لاستخدام البنية المحلية كما لو كانت مثبتة عالميًا:```bash

Bash / Zsh

alias envsec="node $(pwd)/packages/cli/dist/main.js"

Fish

alias envsec "node (pwd)/packages/cli/dist/main.js"

### اختبار اكتمال الأوامر (shell completions) محليًا

بعد البناء وإعداد الاسم المستعار (alias)، قم بتحميل اكتمال الأوامر في جلستك الحالية:```bash
# Bash
alias envsec="node $(pwd)/packages/cli/dist/main.js"
eval "$(envsec --completions bash)"

# Zsh
alias envsec="node $(pwd)/packages/cli/dist/main.js"
eval "$(envsec --completions zsh)"

# Fish
alias envsec "node (pwd)/packages/cli/dist/main.js"
envsec --completions fish | source

ثم اضغط TAB بعد envsec -c لرؤية سياقاتك، أو بعد envsec -c myapp.dev get لرؤية مفاتيح الأسرار.

تشغيل الاختبارات

تغطي اختبارات التكامل الشاملة دورة حياة CLI الكاملة (add، get، list، search، env-file، load، delete، run، cmd، audit، share، completions).```bash

Build first

pnpm run build

macOS / Linux

bash packages/cli/test/e2e-test.sh

Windows (PowerShell)

pwsh packages/cli/test/e2e-test.ps1

يتم تشغيل CI تلقائيًا عند الدفع/PR إلى `main` عبر GitHub Actions، حيث ينفّذ `e2e-test.sh` على macOS وUbuntu، و`e2e-test.ps1` على Windows.

## الترخيص

MIT