cottage

cottage هي أداة GitOps للفرق لإدارة الأسرار المشفّرة بـ age-encrypted في مستودعات git.

توفر سير عمل بسيطًا لتشفير/فك تشفير الأسرار، وإدارة المستلمين، وإبقاء الأسرار خارج المستودع مع السماح بالمشاركة السهلة عبر VCS. كما تولّد cottage معاينات محجوبة (redacted) للأسرار المشفّرة لتحسين الرؤية، وتدعم سير عمل فك التشفير الدائم والمؤقت، مع ضمان عدم إرسال الأسرار أبدًا كنص صريح.

1. الميزات
2. التثبيت
3. تكاملات المحرر
   1. إضافة VS Code
   2. إضافة Cursor و Eclipse
   3. إضافة Vim
4. تكاملات وكلاء الذكاء الاصطناعي
   1. تكامل Claude Code
   2. تكامل GitHub Copilot
   3. تكامل Codex
   4. تكامل Antigravity (agy)
   5. تكامل Cursor
5. البدء السريع
6. GitOps
7. خطافات Git
8. التحكم في الوصول
   1. القواعد
   2. التحقق
9. أي مزوّد كمصدر علوي
   1. أمثلة على الإضافات
10. المزامنة مع أي جهاز
11. معرفة المزيد
12. استكشاف الأخطاء وإصلاحها
13. المقارنة
    1. age مقابل التشفير الآخر
    2. cottage مقابل SOPS
    3. cottage مقابل dotenvx
    4. cottage مقابل agebox

الميزات

• آمن ضد الكشف: يستخدم نظام أنواع Rust لضمان أن الأخطاء لا يمكن أن تكشف الأسرار عن طريق الخطأ.
• صديق للفريق: شارك المفاتيح العامة (المستلمين) في المستودع، واحتفظ بالمفاتيح الخاصة (الهويات) محليًا.
• التحكم في الوصول: قواعد بسيطة للسماح/المنع للتحكم في الأسرار التي يتم تشفيرها لأي مستلمين.
• إدارة .gitignore: يحدّث .gitignore تلقائيًا لإبقاء الأسرار غير المشفّرة خارج المستودع.
• المعاينات: يولّد معاينات محجوبة (redacted) بعلامة زمنية للأسرار المشفّرة لتحسين الرؤية.
• فروقات غنية: يحافظ على git diff نظيفًا وقابلًا للمراجعة، بينما يعرض ctg diff فروقات الأسرار المعدّلة محليًا مقابل نظيراتها المشفّرة المتتبعة.
• التحقق من المجموع الاختباري: يمنع العبث من خلال التحقق من أن الأسرار المشفّرة وقوائم المستلمين تطابق البيانات الوصفية.
• خطافات Git: إعداد خطافات git بسهولة للتحقق/تشفير الأسرار تلقائيًا قبل الالتزام وفك تشفيرها بعد الخروج (checkout).
• سير عمل الأسرار الدائمة: ctg decrypt/sync يحتفظ بالأسرار المفكوكة التشفير على القرص.
• دورة حياة تنظيف ذكية: ctg run (اختصار ctgx) و ctg edit يفكّان تشفير الأسرار قبل العملية، مع إبقائها على القرص إذا كانت موجودة مسبقًا أو تنظيفها تلقائيًا بعد ذلك إذا لم تكن موجودة.
• تنظيف عند الاكتمال: ctg encrypt --clean، ctg run --clean، و تضمن تنظيف الملفات المفكوكة التشفير من القرص حتى لو كانت موجودة من قبل.

التثبيت

# rust: cargo-binstall/cargo
cargo binstall --locked cottage
cargo install --locked cottage

# python: pip/uv/uvx
pip install cottage
uv pip install cottage
uvx --from cottage ctg --version

# node: yarn/pnpm/npx
yarn global add @sayanarijit/cottage
pnpm add -g @sayanarijit/cottage
npx -p @sayanarijit/cottage ctg --version

متاح أيضًا كصور Docker:

# Docker
docker run --rm -v $PWD:/app sayanarijit/cottage --version

# Podman
podman run --rm -v $PWD:/app quay.io/sayanarijit/cottage --version

أو قم بتنزيل أحدث إصدار من GitHub.

تكاملات المحرر

إضافة VS Code

استخدم إضافة Cottage لـ VS Code لتثبيت ctg، وإضافة خطافات أمان Copilot، وتشفير الملفات من المستكشف، وفتح ملفات .cott.age عبر سير عمل المحرر.

قم بتثبيتها من Visual Studio Marketplace، أو قم ببنائها وتثبيتها محليًا من vscode-plugin-cottage.

إضافة Cursor و Eclipse

قم بتنزيل ملف VSX وتثبيته في Cursor أو Eclipse IDE الخاص بك. يعمل بشكل مشابه لإضافة VS Code.

إضافة Vim

استخدم إضافة cottage.vim لتشفير/فك تشفير الأسرار من Vim أو Neovim.

تكاملات وكلاء الذكاء الاصطناعي

جميع التكاملات أدناه تمنع وكلاء الذكاء الاصطناعي من تشغيل ctg/ctgx مباشرة ومن عرض أو تحرير ملفات الأسرار: أي شيء داخل .cottage/، وأي ملف *.cott.* (كتل *.cott.age المشفّرة ومعاينات *.cott.toml المحجوبة)، وأي ملف مفكوك التشفير لا يزال لديه نظير *.cott.age على القرص.

تكامل Claude Code

إذا كنت تستخدم Claude Code، أضف .claude/settings.json و .claude/hooks/deny-secrets.py إلى مستودعاتك التي تحتوي على أسرار حتى تتعامل جلسات Claude Code مع الأسرار بأمان، أو قم بتثبيت إضافة claude-plugin-cottage.

تكامل GitHub Copilot

إذا كنت تستخدم GitHub Copilot في VS Code، أضف .github/hooks/ctg-policy.json و .github/hooks/scripts/deny_ctg_command.py إلى مستودعاتك التي تحتوي على أسرار حتى تقوم جلسات Copilot بتنظيف الملفات المفكوكة التشفير، وحظر أوامر ctg المباشرة في الصدفة، وحظر الوصول إلى ملفات الأسرار، أو قم بتثبيت إضافة vscode-plugin-cottage لإعداد ذلك من VS Code.

يقوم VS Code بتحميل تعريفات خطافات .claude/settings.json أيضًا. إذا احتفظت بملفات خطافات Claude و Copilot في نفس المستودع، فتأكد من عدم تشغيل نفس خطاف التنظيف مرتين عن طريق الخطأ.

تكامل Codex

إذا كنت تستخدم Codex، أضف .codex/hooks.json و .codex/hooks/deny-ctg.py إلى مستودعاتك التي تحتوي على أسرار حتى تتعامل جلسات Codex مع الأسرار بأمان، أو قم بتثبيت إضافة codex-plugin-cottage.

يتطلب Codex مراجعة الخطافات المحلية قبل تشغيلها. بعد إضافة الملفات، ابدأ Codex في المستودع واستخدم /hooks لمراجعة خطافات المشروع والثقة بها.

تكامل Antigravity (agy)

إذا كنت تستخدم Antigravity (agy)، أضف .agents/hooks.json و .agents/scripts/deny-ctg.py إلى مستودعاتك التي تحتوي على أسرار حتى تتعامل جلسات Antigravity مع الأسرار بأمان، أو قم بتثبيت إضافة agy-plugin-cottage.

تكامل Cursor

إذا كنت تستخدم Cursor، أضف .cursor/hooks.json، و .cursor/hooks/deny-ctg.py، و .cursor/hooks/deny-read-secrets.py، و .cursor/rules/deny-ctg.mdc، و .cursorignore إلى مستودعاتك التي تحتوي على أسرار حتى تتعامل جلسات Cursor مع الأسرار بأمان.

يتطلب Cursor تمكين الخطافات أولاً. افتح إعدادات Cursor > Hooks وقم بتمكين الخطافات، ثم أعد تشغيل جلسة الوكيل حتى تسري خطافات المشروع. كما يبقي .cursorignore ملفات الأسرار خارج فهرسة Cursor وسياق الوكيل.

البدء السريع

تهيئة المشروع:

mkdir project && cd project

git init  # اختياري، يعمل cottage بشكل أفضل مع git ولكنه غير مطلوب
ctg init  # يقوم بإعداد دليل .cottage والملفات الضرورية

tree -a
# .
# ├ .cottage/           <- تم إنشاؤه تلقائيًا بواسطة `ctg init`
# │ ├ identity        <- مفتاحك الخاص، احتفظ به بأمان. انقله إلى `~/.config/cottage/identity` لاستخدامه عالميًا، أو استبدله برابط رمزي (soft link) إلى أحد مفاتيحك الخاصة الموجودة.
# │ └ recipients/     <- هذا هو المكان الذي يحتفظ فيه فريقك بالمفاتيح العامة لجميع المستلمين.
# │     └ sayanarijit <- مفتاحك العام. قم بالالتزام به. لاستخدام مفتاح عام موجود، فقط انسخ (لا تستخدم رابطًا رمزيًا) هذا المفتاح هنا.
# ├ .git/...
# ├ .gitattributes      <- تمت إضافة `*.cott.age binary linguist-generated filter=cottage-encrypted -diff` لتجنب تلويث git diff
# └ .gitignore          <- تمت إضافة `/.cottage/identity` لأسباب واضحة

# يمكنك تشغيل `ctg clean --all` في أي وقت لتنظيف كل ما فعله cottage.

إنشاء أو تحرير سر:

# `ctg edit` يفك تشفير الملف قبل فتحه في $EDITOR ويعيد تشفيره عند الحفظ.
# إذا لم يكن الملف المفكوك التشفير موجودًا على القرص قبل تشغيل `ctg edit`، فسيتم تنظيفه بعد ذلك.
# إذا كان موجودًا بالفعل، فسيتم الاحتفاظ به على القرص.
ctg edit secret.yml

# استخدم `--clean` مع `ctg edit` أو `ctg encrypt` لضمان حذف الملفات المفكوكة التشفير حتى لو كانت موجودة من قبل
ctg edit secret.yml --clean    # يفتح في $EDITOR، يشفر عند الحفظ، وينظف
ctg encrypt secret.yml --clean # يشفر secret.yml وينظف
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml
#    edit .gitignore
# delete secret.yml

تشغيل أمر مع أسرار مفكوكة التشفير:

cat secret.yml
# cat: secret.yml: No such file or directory

# `ctg run` (أو الاختصار `ctgx`) يفك تشفير الأسرار قبل تشغيل الأمر.
# إذا لم تكن الملفات المفكوكة التشفير موجودة على القرص مسبقًا، فسيتم تنظيفها تلقائيًا بعد انتهاء الأمر.
# إذا كانت موجودة بالفعل مسبقًا، فسيتم الاحتفاظ بها على القرص.
ctg run -- kubectl apply -f secret.yml          # يفك تشفير secret.yml.cott.age إلى secret.yml ويشغل الأمر
ctg run -- kubectl apply -f secret.yml.cott.age # يستبدل أيضًا وسيط المسار بمسار الملف المفكوك التشفير
ctg run -- kubectl apply -f .                   # يفك تشفير جميع ملفات .cott.age في . ويشغل الأمر
ctg run -- ./deploy.sh                          # يفك تشفير جميع ملفات .cott.age في المستودع ويشغل الأمر

cat secret.yml
# cat: secret.yml: No such file or directory

# استخدم `--clean` لضمان تنظيف الملفات المفكوكة التشفير حتى لو كانت موجودة من قبل
ctg run --clean ./deploy.sh

أو استخدم الاختصار:

ctgx -- ./deploy.sh
ctgx --clean -- ./deploy.sh

تشغيل أمر مع حقن الأسرار كمتغيرات بيئة، دون الكتابة على القرص إطلاقًا:

ctg env -- ./deploy.sh # تصدير الأسرار من .env.cott.age (الافتراضي) دون كتابتها على القرص، ثم تشغيل deploy.sh
ctg env -F .env.prod.cott.age -- ./deploy.sh # التصدير من .env.prod.cott.age بدلاً من .env.cott.age
ctg env -F secrets.json.cott.age -- printenv COTTAGE_SECRET # يدعم أيضًا الملفات غير dotenv.

GitOps

لمشاركة أسرارك مع أعضاء الفريق، فقط ادفع إلى مستودع git.

git add .
git commit -m "Add secret.yml"
git push origin main

اطلب من زملائك إضافة مفاتيحهم العامة إلى .cottage/recipients ودفع التغييرات. ثم يمكنك سحب الأسرار وإعادة تشفيرها لهم.

git pull origin main

ctg decrypt --skip-verify-recipients  # فك تشفير الأسرار المفقودة لإعادة التشفير
ctg encrypt                           # إعادة تشفير جميع الأسرار
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml

ctg clean  # اختياري
# delete secret.yml

# مراجعة التغييرات، الالتزام والدفع
git add .
git commit -m "Add new recipient to secrets"
git push origin main

الآن يمكن لزملائك سحب أحدث التغييرات وفك تشفير الأسرار بأنفسهم.

خطافات Git

يمكنك استخدام prek أو pre-commit لإعداد خطافات git للتحقق/تشفير الأسرار تلقائيًا قبل الالتزام وفك تشفيرها بعد الخروج (checkout).

انظر مثال تكوين prek هنا.

بعد إضافة ملف prek.toml، قم بتشغيل:

prek install
prek install --hook-type post-checkout
prek install --hook-type post-merge
prek install --hook-type post-rewrite

التحكم في الوصول

القواعد

في ملف البيانات الوصفية، يمكنك تحديد المستلمين الذين يجب تشفير السر لهم. يتيح لك ذلك الحصول على أسرار مختلفة لبيئات مختلفة (مثل staging مقابل production) وتشفيرها فقط للمستلمين المعنيين.

# secret.yml.cott.toml
[secret]
allow = ["sayanarijit"]  # تشفير فقط لـ sayanarijit

# secret.yml.cott.toml
[secret]
deny = ["sayanarijit"]  # تشفير للجميع باستثناء sayanarijit

# secret.yml.cott.toml
[secret]
allow = ["env/staging/*"]  # يدعم أنماط glob، تشفير فقط للمستلمين في env/staging
deny = ["env/staging/badservice"]  # تشفير للجميع في env/staging باستثناء badservice

قواعد المنع لها الأولوية على قواعد السماح.

انظر مواصفات البيانات الوصفية لمزيد من التفاصيل.

التحقق

يمكنك تشغيل ctg verify في CI للتحقق من أن الأسرار المشفّرة وقوائم المستلمين تطابق قواعد البيانات الوصفية، لمنع العبث.

# .github/workflows/cottage-verify.yml
name: Cottage Verify
on: [push, pull_request]
permissions:
  contents: read
jobs:
  verify-secrets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Verify secrets
        run: docker run --rm -v "${{ github.workspace }}:/app" ghcr.io/sayanarijit/cottage verify

أي مزوّد كمصدر علوي

مع cottage، يمكنك مزامنة الأسرار مع أي مزوّد لديه واجهة برمجة تطبيقات (API)، وليس فقط git.

لذلك، أنشئ ملفًا باسم cottage.toml في جذر المشروع وقم بتكوين إعدادات المصدر العلوي.

انظر مثال cottage.toml هنا و تكوين المصدر العلوي الخاص بالسر هنا.

انظر مثال تنفيذ إضافة هنا.

سير العمل مشابه لـ git، ولكن بدلاً من git pull و git push، تقوم بتشغيل ctg pull و ctg push لمزامنة الأسرار مع المصدر العلوي المكوّن.

مثال:

# سحب أحدث التغييرات إلى الأسرار المشفّرة محليًا
# مشابه لـ `git pull origin`
ctg pull myvault

# مقارنة الفروقات مع الأسرار المفكوكة التشفير محليًا
ctg diff

# مزامنة الأسرار المفكوكة التشفير محليًا مع الأسرار المشفّرة محليًا
ctg sync

# دفع التغييرات من الأسرار المشفّرة محليًا إلى المصدر العلوي
# مشابه لـ `git push origin main`
ctg push myvault

انظر مواصفات تكوين المصدر العلوي لمزيد من التفاصيل.

أمثلة على الإضافات

يدعم Cottage مزوّدي إضافات مختلفين لمزامنة أسرارك. تتوفر نصوص الإضافات الجاهزة للاستخدام في دليل examples/plugins:

• 1Password
• AWS Secrets Manager
• Azure Key Vault
• Bitwarden
• Dashlane
• Doppler
• ejson
• GitHub Secrets
• Google Cloud Secret Manager
• HashiCorp Vault (انظر أيضًا Vault in Kubernetes)
• Keeper Security
• KeePass (Passhole)
• LastPass
• pass (password-store)
• Proton Pass
• System Keyring
• Zoho Vault

المزامنة مع أي جهاز

استخدم Cottage Sync لمزامنة أسرارك عبر أجهزتك وتصفحها دون الحاجة إلى CLI.

معرفة المزيد

انظر دليل examples لمزيد من أمثلة الاستخدام.

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

# راجع سجلات التصحيح باستخدام -v أو -vv أو -vvv
ctg run -vvv -- ./deploy.sh

المقارنة

age مقابل التشفير الآخر

يستخدم age خوارزمية حديثة وبسيطة محسّنة لتشفير الملفات بشكل آمن، مع التركيز على سهولة الاستخدام وتقليل سطح الهجوم. كما يدعم مفاتيح SSH RSA و Ed25519، على الرغم من أنه يُنصح باستخدام مفاتيح مختلفة لأغراض ونطاقات منفصلة.

cottage مقابل SOPS

بينما يتشارك SOPS و cottage في العديد من الميزات المتداخلة، يتمتع cottage بالمزايا التالية:

• إدارة تلقائية لـ .gitignore لضمان عدم إرسال الأسرار غير المشفّرة إلى git أبدًا.
• كون الأسرار المشفّرة ملفات .age مشفّرة بالكامل بـ age، يتيح ذلك قابلية تشغيل أفضل مع نظام بيئي أوسع من الأدوات.
• فروقات أنظف - على عكس SOPS، الذي يولّد فروقات لكل قيمة من كل سر، حتى لو كان التغيير الفعلي مجرد إضافة/إزالة مستلم، يولّد cottage فرقًا واحدًا فقط لكل ملف، مشيرًا بوضوح إلى التغيير في المجموع الاختباري للمستلمين.

cottage مقابل dotenvx

يستعير cottage واجهة برمجة ctg env من dotenvx.

• يدعم أي نوع ملف، وليس فقط ملفات dotenv.
• يدير أسرارًا متعددة في مستودع.
• قواعد التحكم في الوصول لتشفير الأسرار لمستلمين محددين.
• فروقات أنظف - انظر cottage مقابل SOPS.

cottage مقابل agebox

agebox مشابه جدًا لـ cottage في الفلسفة الأساسية ولكنه يفتقر إلى العديد من الميزات.