هذا هو الادعاء الأساسي وهو قابل للدفاع اليوم ضد اختراق الوكيل، وحقن المطالبات، وسرقة السجلات، وتسريب المهارات.
اقرأ [docs/THREAT-MODEL.md](https://github.com/rohansx/wardn/blob/HEAD/docs/THREAT-MODEL.md) للتقسيم الصادق بين ما هو مغطى وما هو غير مغطى — بما في ذلك المستوى الذي يصبح فيه الادعاء الأقوى 'اختراق المضيف لا يسرب شيئًا' قابلاً للتحقيق.

الخزانة نفسها (مشفرة في وضع السكون، ومفتاح مشتق من عبارة المرور) هي مكون حقيقي وسبب قدرة الجدار الناري على العمل على جهاز واحد.
المستوى القادم [docs/HOSTED-TIER.md](https://github.com/rohansx/wardn/blob/HEAD/docs/HOSTED-TIER.md) يغلف الوكيل أيضًا في بيئة حوسبة سرية بحيث حتى الخادم الافتراضي الخاص المخترق بالكامل لا يمكنه قراءة المفتاح.

[![Crates.io](https://img.shields.io/crates/v/wardn.svg)](https://crates.io/crates/wardn)
[![License](https://img.shields.io/crates/l/wardn.svg)](LICENSE)

## المشكلة

كل إطار وكيل ذكاء اصطناعي اليوم يخزن مفاتيح API في متغيرات البيئة أو ملفات `.env`. الوكيل المخترق، أو المهارة الخبيثة، أو أداة السرقة الشائعة، أو حقن المطالبات الذي يسرب `Authorization: Bearer sk-...` من سجل LLM يحصل على وصول كامل إلى بيانات اعتمادك.```
~/.env              → OPENAI_KEY=sk-proj-real-key      # plaintext, readable by anyone
agent context       → "Use OPENAI_KEY=sk-proj-real-key" # leaked into LLM context window
agent logs          → Authorization: Bearer sk-proj-... # sitting in log files

## الهندسة المعمارية```mermaid
flowchart TB
    subgraph Agent["AI Agent Process"]
        A1["Agent Code"]
        A2["ENV: OPENAI_KEY=wdn_placeholder_a1b2..."]
    end

    subgraph Wardn["wardn daemon · localhost:7777"]
        direction TB
        P["HTTP Proxy"]
        MCP["MCP Server\n(stdio)"]

        subgraph Pipeline["Request Pipeline"]
            direction LR
            S1["Identify\nAgent"] --> S2["Resolve\nPlaceholder"] --> S3["Check\nAuth"] --> S4["Rate\nLimit"] --> S5["Inject\nReal Key"]
        end

        subgraph ResponsePipeline["Response Pipeline"]
            direction RL
            R1["Strip Real\nKeys"] --> R2["Replace with\nPlaceholders"]
        end

        subgraph Vault["Encrypted Vault"]
            V1["AES-256-GCM"]
            V2["Argon2id KDF"]
            V3["Placeholder Map\nper agent × credential"]
        end
    end

    subgraph External["External APIs"]
        E1["api.openai.com"]
        E2["api.anthropic.com"]
        E3["..."]
    end

    A1 -- "placeholder token\nin headers/body" --> P
    A1 -. "MCP: get_credential_ref\nlist_credentials\ncheck_rate_limit" .-> MCP
    MCP -. "placeholder token\n(never real keys)" .-> A1
    P --> Pipeline
    Pipeline --> External
    External --> ResponsePipeline
    ResponsePipeline -- "response with\nplaceholders only" --> A1
    Pipeline <--> Vault
    ResponsePipeline <--> Vault

    style Agent fill:#1a1a2e,stroke:#e94560,color:#fff
    style Wardn fill:#0f3460,stroke:#16213e,color:#fff
    style Pipeline fill:#16213e,stroke:#e94560,color:#fff
    style ResponsePipeline fill:#16213e,stroke:#e94560,color:#fff
    style Vault fill:#1a1a2e,stroke:#00d2ff,color:#fff
    style External fill:#0a0a0a,stroke:#533483,color:#fff

## عرض توضيحي

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12823/1fa6109ffd855ec98c173c5edd2d7ee77f6b0c918a3cdecb1ea5fbfe8326161d.gif" alt="عرض توضيحي لـ wardn" width="800">
</p>

## مستويات الثقة، بصراحة

| المستوى | المكان | المضمون |
|---|---|---|
| **الاستضافة الذاتية (حاليًا)** | حاسوبك المحمول، خادمك الخاص، CI | خزنة مشفرة عند الراحة، ادعاء جدار حماية ضد الوكلاء. **لا** يدافع ضد صلاحية الجذر على المضيف. |
| **مستضافة (قادمة)** | مُدارة بواسطة wardn أو سحابتك الخاصة | بيئة حوسبة سرية (Nitro / SEV-SNP) + شهادة عن بُعد + تدفق التشفير إلى الوكيل. ادعاء حقيقي "اختراق المضيف لا يُسرب شيئًا". |

مستوى الاستضافة الذاتية هو الادعاء الأساسي ويتم إطلاقه اليوم. المستوى المستضاف هو مسار الترقية الصارم: يتطلب تكاليف مالية وتعقيد تشغيلي، وتصميمه موجود في [docs/HOSTED-TIER.md](https://github.com/rohansx/wardn/blob/HEAD/docs/HOSTED-TIER.md). جرد كامل وصادق لما يتم تغطيته وما لا يتم تغطيته:

👉 **[docs/THREAT-MODEL.md](https://github.com/rohansx/wardn/blob/HEAD/docs/THREAT-MODEL.md)** — جدول يغطي / لا يغطي، مذكور بوضوح "لا يوجد خزنة برمجية تقضي على اختراق المضيف"، ومسار الترقية.

## تثبيت```bash
# Prebuilt binary (Linux/macOS, amd64/arm64), checksum-verified
curl -sSf https://raw.githubusercontent.com/rohansx/wardn/main/install.sh | sh

# or from crates.io
cargo install wardn

# or Homebrew, once the tap is published (see Formula/wardn.rb)
brew install rohansx/wardn/wardn

هذا كل شيء. يستخدم Claude Code الآن خادم MCP الخاص بـ wardn للحصول على رموز نائبة بدلاً من قراءة المفاتيح الحقيقية من بيئتك.

### ماذا يحدث بعد ذلك

1. يقوم Claude Code باستدعاء `get_credential_ref` → يحصل على `wdn_placeholder_a1b2...` (وليس المفتاح الحقيقي)
2. يرسل الوكيل الطلب مع الرمز النائب عبر وكيل wardn
3. يقوم الوكيل باستبدال الرمز النائب بالمفتاح الحقيقي، ويعيد توجيهه إلى واجهة API
4. يقوم الوكيل بإزالة المفتاح الحقيقي من الاستجابة قبل إعادتها إلى الوكيل

لا يدخل المفتاح الحقيقي أبدًا إلى ذاكرة الوكيل أو سجلاته أو نافذة سياق LLM.

## لوحة التحكم المحلية

بمجرد تشغيل البرنامج الخفي (`wardn serve`، أو يتم تشغيله بواسطة `wardn run`)، افتح
**http://127.0.0.1:7777/ui** في متصفح. عرض محلي للقراءة فقط:

- **بيانات الاعتماد** — كل بيانات اعتماد مخزنة مع قوائم التحكم بالوصول الخاصة بها (الوكلاء المسموح لهم، النطاقات المسموح بها، حد المعدل + شارات الميزانية).
- **النشاط الأخير** — آخر 50 حدثًا للوكيل مع الطريقة، النطاق، المسار، الحالة، الوكيل، معرف الطلب، والتكلفة المسجلة (`request_completed`، `credential_injected`، `rate_limit`، `budget_exceeded`، `loop_detected`، `request_error`).
- **الميزانيات** — ميزانية كل بيانات اعتماد مُهيأة (الحد الأقصى، المُستهلك، المتبقي، النافذة، الوضع) مع شريط تقدم يتحول من تحذيري إلى سيئ عند تجاوز 50% / 80%.

يتم الاستقصاء تلقائيًا كل 2 ثانية. لا توجد نقاط نهاية للتعديل — الطريقة الوحيدة للخروج من لوحة التحكم هي واجهة API نفسها (`/api/summary`، `/api/credentials`، `/api/audit?limit=N`، `/api/budgets`).```bash
# Static, anonymous, never sees real keys
curl http://127.0.0.1:7777/api/summary | jq

## مرجع CLI

### إدارة Vault```bash
wardn vault create                        # create encrypted vault
wardn vault set OPENAI_KEY                # store credential (prompts for value, no echo)
wardn vault get OPENAI_KEY                # get placeholder token (never the real value)
wardn vault get OPENAI_KEY --agent bot    # get placeholder for specific agent
wardn vault list                          # list all credentials
wardn vault rotate OPENAI_KEY             # rotate value, placeholders unchanged
wardn vault remove OPENAI_KEY             # remove credential

# Custom vault path
wardn --vault /path/to/vault.enc vault list

### Claude Code / Cursor Integration```bash
wardn setup claude-code                   # register wardn as MCP server in Claude Code
wardn setup cursor                        # register wardn as MCP server in Cursor

# Or manually:
claude mcp add --transport stdio --scope user wardn -- wardn serve --mcp --agent claude-code

#### أدوات MCP المتاحة

| الأداة | ما ترجعه | الأمان |
|------|----------------|----------|
| `get_credential_ref` | رمز مؤقت (`wdn_placeholder_...`) | ليس القيمة الحقيقية أبدًا |
| `list_credentials` | أسماء بيانات الاعتماد + البيانات الوصفية | مصفاة حسب وصول الوكيل |
| `check_rate_limit` | الحصة المتبقية، معلومات إعادة المحاولة | للقراءة فقط |

### ترحيل بيانات الاعتماد```bash
wardn migrate --dry-run                             # audit Claude Code dir for exposed keys
wardn migrate --source claude-code                  # scan + migrate to vault
wardn migrate --source open-claw                    # scan OpenClaw config
wardn migrate --source directory --path ./my-proj   # scan any directory

يطلب كل أداة استيراد عبارة مرور الخزنة عند الاستخدام الأول (أو يقرأها من `WARDN_PASSPHRASE` / سلسلة المفاتيح الخاصة بنظام التشغيل). يتم الكتابة فوق القيم الموجودة بصمت — تقوم أداة الاستيراد باستيراد القيم فقط، ويتم الحفاظ على البيانات الوصفية (العوامل المسموح بها / النطاقات / حد المعدل / الميزانية).

### الأتمتة

بالنسبة لـ CI/النصوص، قم بتعيين متغيرات البيئة `WARDN_PASSPHRASE` و `WARDN_VALUE` لتخطي المطالبات التفاعلية:```bash
WARDN_PASSPHRASE=my-pass wardn vault list
WARDN_PASSPHRASE=my-pass WARDN_VALUE=sk-proj-xxx wardn vault set OPENAI_KEY

### عمليات الخزنة```rust
use wardn::{Vault, config::CredentialConfig};

// Create an encrypted vault
let vault = Vault::create("vault.enc", "my-passphrase")?;

// Store a credential
vault.set_with_config("OPENAI_KEY", "sk-proj-real-key-123", &CredentialConfig {
    allowed_agents: vec!["researcher".into(), "writer".into()],
    allowed_domains: vec!["api.openai.com".into()],
    rate_limit: Some(RateLimitConfig { max_calls: 200, per: TimePeriod::Hour }),
})?;

// Agent gets a placeholder (not the real key)
let placeholder = vault.get_placeholder("OPENAI_KEY", "researcher")?;
// → "wdn_placeholder_a1b2c3d4e5f6g7h8"

// Rotate the real key — all placeholders keep working
vault.rotate("OPENAI_KEY", "sk-proj-new-key-456")?;

### MCP Server```rust
use wardn::mcp::WardenMcpServer;

// Serve over stdio (for Claude Code, Cursor, etc.)
WardenMcpServer::serve_stdio(vault, rate_limiter, "agent-id".into()).await?;

اضبط `RUST_LOG=wardn=info` (أو `debug`/`trace`) للتحكم في مستوى التفاصيل. تذهب السجلات إلى stderr، وليس stdout.

## الإعدادات```toml
[warden]
vault_path = "~/.vibeguard/vault.enc"

[warden.credentials.OPENAI_KEY]
rate_limit = { max_calls = 200, per = "hour" }
allowed_agents = ["researcher", "writer"]
allowed_domains = ["api.openai.com"]

[warden.credentials.ANTHROPIC_KEY]
rate_limit = { max_calls = 100, per = "hour" }
allowed_agents = ["researcher"]
allowed_domains = ["api.anthropic.com"]

## التطوير```bash
# Integration tests use a fast (insecure) KDF so the suite runs in
# milliseconds instead of paying the real Argon2id cost per test —
# always pass this feature flag when running tests locally or in CI:
cargo test --features test-fast-kdf

cargo build
cargo clippy --all-targets --features test-fast-kdf

subgraph KDF["Key Derivation"]
    Argon["Argon2id\nm=19456 t=2 p=1"]
end

subgraph Encrypt["Encryption"]
    AES["AES-256-GCM"]
    Nonce["Random Nonce\n(12 bytes)"]
end

subgraph Output["WDNV File"]
    direction TB
    Magic["WDNV (4B)"]
    Ver["Version (2B)"]
    SaltOut["Salt (16B)"]
    Payload["Nonce ‖ Ciphertext ‖ Tag"]
end

Pass --> Argon
Salt --> Argon
Argon -- "256-bit key" --> AES
Creds --> AES
Nonce --> AES
AES --> Payload

style Input fill:#1a1a2e,stroke:#e94560,color:#fff
style KDF fill:#16213e,stroke:#00d2ff,color:#fff
style Encrypt fill:#16213e,stroke:#00d2ff,color:#fff
style Output fill:#0f3460,stroke:#533483,color:#fff

### تنسيق الملف```
Bytes 0-3:   Magic "WDNV"
Bytes 4-5:   Version (u16 LE)
Bytes 6-21:  Argon2id salt (16 bytes)
Bytes 22+:   AES-256-GCM encrypted payload (nonce ‖ ciphertext ‖ tag)