cottage v0.6.7

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

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

1. الميزات
2. التثبيت
3. تكاملات المحرر
   1. امتداد VS Code
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 تلقائيًا لإبقاء الأسرار غير المشفّرة خارج المستودع.
• المعاينات: يولّد معاينات منقّحة بختم زمني للأسرار المشفّرة لتحسين الرؤية.
• فروقات غنية: يُبقي git diff نظيفًا وقابلًا للمراجعة، بينما يعرض ctg diff الفروقات بين الأسرار المعدّلة محليًا ونظيراتها المشفّرة المتتبَّعة.
• التحقق من المجموع الاختباري: يمنع العبث من خلال التحقق من تطابق الأسرار المشفّرة وقوائم المستلمين مع البيانات الوصفية.
• خطافات git: أنشئ بسهولة خطافات git للتحقق من الأسرار/تشفيرها تلقائيًا قبل الالتزام وفك تشفيرها بعد checkout.
• سير عمل الأسرار الدائمة: ctg decrypt/edit/sync يُبقي الأسرار مفكوكة التشفير على القرص.
• سير عمل الأسرار المؤقتة: ctg run (الاختصار ctgx) يفك تشفير الأسرار مؤقتًا لتشغيل أمر، ثم يحذفها بغضّ النظر عن نجاح الأمر أو فشله.
• سير عمل حقن البيئة: ctg env يحقن الأسرار مفكوكة التشفير كمتغيرات بيئة لتشغيل أمر، دون كتابتها على القرص إطلاقًا.
• التنظيف: ctg clean يحذف جميع الأسرار مفكوكة التشفير من المستودع المحلي ليتيح لك تشغيل وكلاء الذكاء الاصطناعي بقلق أقل.
• يدعم jj والمجلدات غير git: ctg init يحوّل أي مجلد إلى مخزن أسرار.
• المزامنة مع أي موفّر: يتيح لك ضبط أي موفّر يملك API كمصدر علوي (upstream)، وبدء استخدام ctg pull/diff/push مثل git pull/diff/push.
• المزامنة مع أي جهاز: يمكن مزامنة الأسرار المشفّرة بـ cottage والمدارة في مستودع git عبر الأجهزة باستخدام Cottage Sync.

التثبيت

# 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، وتشفير الملفات من المستكشف (Explorer)، وفتح ملفات .cott.age عبر سير عمل المحرر.

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

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

جميع التكاملات أدناه تمنع وكلاء الذكاء الاصطناعي من تشغيل 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 Settings > Hooks وفعّل الخطافات، ثم أعد تشغيل جلسة الوكيل ليبدأ سريان خطافات المشروع. إضافة إلى ذلك، يُبقي .cursorignore ملفات الأسرار خارج فهرسة Cursor وسياق الوكيل.

البدء السريع

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

mkdir project && cd project

git init  # Optional, cottage works better with git but it's not required
ctg init  # Sets up the .cottage directory and necessary files

tree -a
# .
# ├ .cottage/           <- Auto-generated by `ctg init`
# │ ├ identity        <- Your private key, keep it safe. Move it to `~/.config/cottage/identity` to use it globally, or replace it with a soft link to one of your existing private keys.
# │ └ recipients/     <- This is where your team keeps the public keys of all the recipients.
# │     └ sayanarijit <- Your public key. Commit it. To use an existing public key, just copy (don't softlink) that key here.
# ├ .git/...
# ├ .gitattributes      <- Added `*.cott.age binary export-ignore filter=cottage-encrypted -diff` to avoid polluting git diff
# └ .gitignore          <- Added `/.cottage/identity` for obvious reasons

# You can run `ctg clean --all` anytime to clean up everything cottage ever did.

أنشئ سرًا أو عدّله.

ctg edit secret.yml --clean    # Opens secret.yml in $EDITOR
ctg encrypt secret.yml --clean # Another way to encrypt secrets
# 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 kubectl apply -f secret.yml          # decrypts secret.yml.cott.age to secret.yml and runs the command
ctg run kubectl apply -f secret.yml.cott.age # also replaces the path argument with the decrypted file path
ctg run kubectl apply -f .                   # decrypts all .cott.age files in . and runs the command
ctg run ./deploy.sh                          # decrypts all .cott.age files in repo and runs the command

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

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

ctgx ./deploy.sh  # same as ctg run -- ./deploy.sh

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

ctg env -- ./deploy.sh # Export secrets from .env.cott.age (default) without writing them to disk, then run deploy.sh
ctg env -F .env.prod.cott.age -- ./deploy.sh # exports from .env.prod.cott.age instead of .env.cott.age
ctg env -F secrets.json.cott.age -- printenv COTTAGE_SECRET # Also supports non-dotenv files.

GitOps

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

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

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

git pull origin main

ctg sync  # or `ctg decrypt && ctg encrypt`
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml

ctg clean  # optional
# delete secret.yml

# review changes, commit and push
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"]  # Only encrypt for sayanarijit

# secret.yml.cott.toml
[secret]
deny = ["sayanarijit"]  # Encrypt for everyone except sayanarijit

# secret.yml.cott.toml
[secret]
allow = ["env/staging/*"]  # Supports glob patterns, only encrypt for recipients in env/staging
deny = ["env/staging/badservice"]  # Encrypt for everyone in env/staging except 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 لمزامنة الأسرار مع المصدر العلوي المُهيأ.

مثال:

# Pull latest changes into local encrypted secrets
# Similar to `git pull origin`
ctg pull myvault

# Compare diff with local decrypted secrets
ctg diff

# Sync local decrypted secrets with local encrypted secrets
ctg sync

# Push changes from local encrypted secrets to upstream
# Similar to `git push origin main`
ctg push myvault

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

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

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

• 1Password
• AWS Secrets Manager
• Azure Key Vault
• Bitwarden
• Dashlane
• Doppler
• ejson
• 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 لمزيد من أمثلة الاستخدام.

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

# See debug logs with -v, -vv or -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 في الفلسفة الأساسية لكنه يفتقر إلى العديد من الميزات.