kreftjs 0.0.19-beta → 0.0.20-beta

package/book/ar/05-arabic-rtl.md

@@ -0,0 +1,175 @@
+# الفصل الخامس: العربية والترجمة والاتجاه (RTL)
+
+Kreft يترجم النصوص ويقلب الاتجاه للغات التي تُكتب من اليمين إلى اليسار: العربية والعبرية والفارسية والأردية. هذا الفصل مخصص لنا.
+
+## ملفات الترجمة
+
+المشروع الجديد يأتي بمجلد `lang/` في جذره، وفيه العربية والإنجليزية جاهزتان: `lang/ar.json` و`lang/ar/messages.json` و`lang/ar/validation.json` و`lang/ar/pagination.json` (ويُقرأ أيضًا `frontend/lang/` و`backend/lang/` و`resources/lang/`). استعمل `lang/ar.json` للنصوص البسيطة، أو `lang/ar/messages.json` للمفاتيح المجمّعة.
+
+```json
+// lang/ar/messages.json
+{
+  "welcome": "أهلًا بك في تطبيقي",
+  "hello": "مرحبًا، :name",
+  "items": "{0} لا توجد عناصر|{1} عنصر واحد|{2} عنصران|[3,10] :count عناصر|[11,*] :count عنصرًا"
+}
+```
+
+```json
+// lang/en/messages.json
+{
+  "welcome": "Welcome to my app",
+  "hello": "Hello, :name",
+  "items": "{0} No items|{1} One item|[2,*] :count items"
+}
+```
+
+وفي أي صفحة:
+
+```html
+<h1>{$t('messages.hello', { name: user.name })}</h1>
+<p>{$choice('messages.items', count)}</p>
+```
+
+- الرسالة تستعمل `:name` للقيم.
+- للجمع افصل الصيغ بـ `|`، وحدّد المجال بين `{}` للقيمة الواحدة (`{0}` و`{2}`) أو `[من,إلى]` (`[3,10]` و`[11,*]`). هذا يناسب العربية تمامًا: صفر، وواحد، واثنان، وجمع القلة (3–10)، وما فوق (11+) بصيغة التمييز المنصوب.
+
+## تبديل اللغة
+
+```js
+Kreftjs.locale('ar')          // يتبدّل <html lang> و dir وتُعاد رسم كل الصفحات
+Kreftjs.fallbackLocale('en')  // اللغة الاحتياطية
+Kreftjs.locales()             // اللغات المحمّلة
+Kreftjs.translations('ar', { 'app.title': 'تطبيقي' })  // نصوص إضافية من الشيفرة
+```
+
+## مبدّل لغة كامل (مع التذكّر)
+
+```html
+<!-- components/LangSwitch.kreft -->
+saved lang = 'ar' as 'app.lang'
+
+watch lang { Kreftjs.locale(value) }
+on start { Kreftjs.locale(lang) }
+
+<view>
+  <button class="lang" @click="lang = lang === 'ar' ? 'en' : 'ar'">
+    {lang === 'ar' ? 'English' : 'العربية'}
+  </button>
+</view>
+```
+
+- `saved` يتذكر الاختيار بعد إعادة التحميل.
+- `watch` يطبّق اللغة عند كل تغيير.
+- `on start` يطبّقها عند فتح الصفحة.
+
+## الاتجاه
+
+يُضبط `dir` تلقائيًا من اللغة، ويمكنك ربطه بيدك:
+
+```html
+<view dir={isArabic ? 'rtl' : 'ltr'}>…</view>
+```
+
+## اكتب CSS ينقلب وحده
+
+استعمل الخصائص المنطقية (logical properties) بدل left/right:
+
+| تجنّب | استعمل |
+|---|---|
+| `margin-left` / `margin-right` | `margin-inline-start` / `margin-inline-end` |
+| `padding-left` / `padding-right` | `padding-inline-start` / `padding-inline-end` |
+| `left: 0` / `right: 0` | `inset-inline-start: 0` / `inset-inline-end: 0` |
+| `text-align: left` / `right` | `text-align: start` / `end` |
+| `border-left` / `border-right` | `border-inline-start` / `border-inline-end` |
+
+```css
+.sidebar {
+  position: fixed;
+  inset-inline-start: 0;           /* يسار في LTR، يمين في RTL */
+  padding-inline-start: 24px;
+  border-inline-end: 1px solid var(--border);
+}
+
+[dir="rtl"] .back-arrow { transform: scaleX(-1); }    /* اقلب أيقونة */
+```
+
+## نصائح عملية للتطبيقات العربية
+
+1. **الأرقام:** استعمل `Intl.NumberFormat('ar-EG')` للأرقام الهندية أو `ar-SA`/`ar-MA` لما تفضله بلدك:
+   ```html
+   derive fmt = new Intl.NumberFormat(lang === 'ar' ? 'ar-EG' : 'en-US')
+   <p>{fmt.format(total)}</p>
+   ```
+2. **التواريخ:** `new Date().toLocaleDateString('ar', { dateStyle: 'long' })`. اختر التقويم بـ `ar-SA-u-ca-islamic` إذا أردت الهجري.
+3. **الخطوط:** اختر خطًا عربيًا (مثل Cairo أو Tajawal). في تطبيقات سطح المكتب لا تعتمد على تحميل خط من الإنترنت؛ ضمّن الخط محليًا.
+4. **الأيقونات الاتجاهية:** الأسهم والرجوع تحتاج `scaleX(-1)` في RTL كما في المثال.
+5. **النص المختلط:** اللاتينية داخل العربية قد تبدّل ترتيب علامات الترقيم. غلّف المقطع بـ `<bdi>` أو `unicode-bidi: isolate`.
+6. **حقول الإدخال:** للبريد والرقم السري وأرقام الهاتف أضف `dir="ltr"` حتى تُكتب صحيحة.
+
+```html
+<input type="email" dir="ltr" k-model="form.email" placeholder="name@example.com">
+```
+
+## على الخادم
+
+لغة الطلب تأتي من `?lang=` أو كوكي `lang` أو `Accept-Language`، ورسائل الخادم تُقرأ من `lang/<locale>/`، والعربية جاهزة في المشروع الجديد:
+
+```json
+// lang/ar/validation.json  (موجود أصلًا في المشروع الجديد)
+{
+  "required": "حقل :attribute مطلوب.",
+  "email": "يجب أن يكون :attribute عنوان بريد إلكتروني صالح.",
+  "min": { "string": "يجب أن يحتوي :attribute على :min أحرف على الأقل." },
+  "attributes": { "email": "البريد الإلكتروني", "password": "كلمة المرور" },
+  "not_common_password": "كلمة المرور شائعة جدًا أو سهلة التخمين. اختر غيرها."
+}
+```
+
+المفتاح `attributes` يترجم أسماء الحقول داخل الرسائل: فتظهر "حقل البريد الإلكتروني مطلوب" بدل "حقل email مطلوب".
+
+وللتخصيص الدقيق لنموذج بعينه استعمل `messages()` في `FormRequest`.
+
+## مثال: صفحة هبوط ثنائية اللغة مع SEO
+
+```html
+<!-- pages/Home.kreft -->
+import LangSwitch from '../components/LangSwitch.kreft'
+
+state count = 3
+
+<view>
+  <header class="top">
+    <h1>{$t('messages.hello', { name: 'الزائر' })}</h1>
+    <lang-switch></lang-switch>
+  </header>
+  <p>{$choice('messages.items', count)}</p>
+  <button @click="count++">+</button>
+</view>
+
+<style scoped>
+.top {
+  display: flex;
+  justify-content: space-between;
+  padding-inline: 24px;
+}
+</style>
+```
+
+ولظهور الصفحة صحيحة لمحركات البحث بلغتين، أعلن البدائل في `backend/routes/seo.js` (انظر فصل النشر):
+
+```js
+module.exports = {
+  '/': {
+    title: 'متجري',
+    description: 'كل ما يحتاجه بيتك',
+    alternates: { en: 'https://example.com/', ar: 'https://example.com/ar/' },
+  },
+}
+```
+
+## تمارين
+
+1. اجعل تطبيقك ثنائي اللغة (عربي/إنجليزي) واحفظ اللغة المختارة.
+2. حوّل كل `margin-left` و`padding-right` في CSS تطبيقك إلى خصائص منطقية وجرّب التبديل.
+3. اكتب مكوّن سعر يعرض المبلغ بالأرقام الهندية عند العربية.

package/book/ar/06-backend.md

@@ -0,0 +1,247 @@
+# الفصل السادس: الواجهة الخلفية
+
+المشروع الذي ينشئه `kreft new` فيه واجهة خلفية على Node.js. الأمران `kreft dev` و`kreft serve` يحمّلان `backend/routes/api.js` بنفسيهما، وكل عنوان فيه يبدأ بـ `/api`، و`kreft dev` يلتقط كل تغيير تحفظه. مجلد `backend` لا يصل المتصفح أبدًا.
+
+## المسارات (Routes)
+
+```js
+// backend/routes/api.js
+const { Route } = require('kreftjs/server')
+const PostController = require('../app/Http/Controllers/PostController')
+
+Route.get('/hello', (req) => ({ hello: req.input('name', 'world') }))      // GET /api/hello
+
+Route.apiResource('posts', PostController)    // index, store, show, update, destroy
+Route.get('/posts/{post}/comments', [PostController, 'comments']).name('posts.comments')
+
+Route.middleware('auth').group(() => {
+  Route.delete('/posts/{post}', [PostController, 'destroy'])
+})
+
+Route.prefix('admin').middleware(['auth', 'admin']).group(() => { /* … */ })
+```
+
+- المعاملات تُكتب `{post}`، أو `{post?}` إن كانت اختيارية.
+- للمسار اسم (`.name('…')`) ونمط (`.whereNumber('id')`) ووسيط (`.middleware('auth')`).
+- `kreft route:list` يطبع كل المسارات مع أسمائها ومتحكماتها ووسطائها.
+
+### فضاءات الأسماء (Namespaces)
+
+فضاءات الأسماء بأسلوب PHP مدعومة للمتحكمات والنماذج والعلاقات:
+
+```js
+const { Route, use, namespace } = require('kreftjs/server')
+
+const User = use('App\\Models\\User')
+const { DashboardController, UserController } = namespace('App\\Http\\Controllers\\Admin')
+
+Route.namespace('Admin').group(() => {
+  Route.get('/users', 'UserController@index')
+  Route.apiResource('users', 'UserController')
+})
+```
+
+## المتحكمات (Controllers) والطلب
+
+دالة المتحكم تستلم الطلب أولًا، ثم معاملات المسار. ما تعيده يُرسل كـ JSON، وإن لم تعد شيئًا فالجواب `204`.
+
+```js
+const { response, abort } = require('kreftjs/server')
+const Post = require('../../Models/Post')
+
+class PostController {
+  async index(req) {
+    return Post.with('author').where('published', true).latest().paginate(15, req.integer('page', 1))
+  }
+
+  async store(req) {
+    const data = await req.validate({
+      title: 'required|max:200|unique:posts,title',
+      author_id: 'required|exists:authors,id',
+    })
+    return response(await Post.create(data), 201)
+  }
+
+  async show(req, id) { return Post.findOrFail(id) }               // 404 إن لم يوجد
+  async destroy(req, id) { await (await Post.findOrFail(id)).delete() }
+}
+
+module.exports = PostController
+```
+
+ولتوليد متحكم: `kreft make:controller PostController --api` (وأيضًا `--model Post` و`--route=api` و`--auth`).
+
+### الطلب (req)
+
+| الاستدعاء | يعطي |
+|---|---|
+| `req.input('name', default)` و`req.all()` و`req.only('a', 'b')` و`req.except(…)` و`req.has(…)` و`req.filled(…)` | قيمًا من الجسم والاستعلام. |
+| `req.boolean('x')` و`req.integer('page', 1)` و`req.string('q')` | قيمة بالنوع الصحيح. |
+| `await req.validate(rules)` | القواعد نفسها كما في `form()`، إضافة إلى `unique:table,column` و`exists:table,column`. يعيد الحقول المفحوصة فقط أو يجيب `422`. |
+| `req.params` و`req.query` و`req.body` و`req.header('x')` و`req.bearerToken()` و`req.ip()` و`req.user` | الباقي. |
+| `req.file('avatar').store('avatars')` | يحفظ رفعًا باسم عشوائي. |
+| `response(data, 201)` و`response(data).header('X', 'y')` و`abort(403, 'message')` | الأجوبة. |
+
+### طلبات النماذج والموارد والسياسات
+
+للنقاط الأكبر، انقل القواعد والتفويض خارج المتحكم:
+
+```js
+// app/Http/Requests/StorePostRequest.js
+const { FormRequest } = require('kreftjs/server')
+
+class StorePostRequest extends FormRequest {
+  authorize(req) { return req.user != null }           // false تجيب 403
+  rules() { return { title: 'required|max:200', body: 'required' } }
+  messages() { return { 'title.required': 'أعطِ المقال عنوانًا.' } }
+}
+
+module.exports = StorePostRequest
+```
+
+```js
+const data = await StorePostRequest.validate(req)                // في متحكم
+return PostResource.collection(await Post.paginate(15))          // { data, meta }
+await req.authorize('update', post)                              // app/Policies/PostPolicy.js
+```
+
+ولتوليدها: `kreft make:request` و`kreft make:resource` و`kreft make:policy`.
+
+## النماذج (Models) وقاعدة البيانات
+
+النماذج أصناف Active Record، كما في Eloquent:
+
+```js
+// app/Models/Post.js
+const { Model, Str } = require('kreftjs/server')
+
+class Post extends Model {
+  static fillable = ['title', 'body', 'user_id']        // ما يجوز لـ create() و update() ملؤه
+  static hidden = []                                    // لا يُرسل كـ JSON أبدًا
+  static casts = { published: 'boolean', meta: 'json' }
+  static softDeletes = true                             // delete() يملأ deleted_at
+
+  user() { return this.belongsTo(require('./User')) }
+  comments() { return this.hasMany(require('./Comment')) }
+  tags() { return this.belongsToMany(require('./Tag')) }
+
+  static scopePublished(q) { q.where('published', true) }
+  static async creating(post) { post.slug ??= Str.slug(post.title) }
+}
+
+module.exports = Post
+```
+
+الجدول هو جمع اسم الصنف (`Post` ← `posts`)؛ استعمل `static table = '…'` لجدول آخر.
+
+### الاستعلام
+
+```js
+await Post.all()
+await Post.find(5)                       // أو findOrFail(5): 404 إن لم يوجد
+await Post.where('published', true).orderByDesc('id').limit(10).get()
+await Post.where('views', '>', 100).orWhere('pinned', true).count()
+await Post.query().published().with('user', 'comments.author').withCount('comments').paginate(15, page)
+await Post.query().whereHas('comments', (q) => q.where('approved', true)).get()
+
+const post = await Post.create({ title: 'مرحبًا' })     // يملأ created_at و updated_at
+await post.update({ title: 'أهلًا' })
+await post.delete()
+
+await post.comments().create({ body: 'جميل' })
+await post.tags().sync([1, 2, 3])                   // وأيضًا attach() و detach() و toggle()
+```
+
+العلاقات: `hasOne` و`hasMany` و`belongsTo` و`belongsToMany` (مع `pivot`) و`hasManyThrough`. الصفوف المحذوفة حذفًا ناعمًا تعود بـ `withTrashed()` وتُسترجع بـ `restore()`.
+
+بلا نموذج:
+
+```js
+await DB.table('orders').join('users', 'users.id', '=', 'orders.user_id').groupBy('status').get()
+await DB.select('SELECT * FROM posts WHERE id = ?', [5])
+await DB.transaction(async () => { await Order.create({ /* … */ }); await Stock.decrement(/* … */) })   // الكل أو لا شيء
+```
+
+> **تحذير:** القيم تسافر دائمًا كمعاملات (`?`). لا تبنِ SQL بضمّ مدخلات المستخدم في نص. أما `whereRaw` و`selectRaw` و`orderByRaw` فتأخذ SQL خامًا عمدًا: مرّر قيم المستخدم عبر مصفوفة المعاملات فيها.
+
+### قواعد البيانات
+
+تأتي القاعدة من `DATABASE_URL` في `.env`:
+
+```env
+DATABASE_URL=sqlite:backend/database/app.db                  # مدمجة في Node.js، لا شيء لتثبيته
+DATABASE_URL=mysql://user:pass@localhost:3306/shop           # npm i mysql2
+DATABASE_URL=postgres://user:pass@localhost:5432/shop        # npm i pg
+```
+
+الترحيلات والنماذج نفسها تعمل على الثلاث.
+
+## الترحيلات (Migrations) والبذور (Seeders) والمصانع (Factories)
+
+الترحيل يصف جدولًا بـ JavaScript، والملف نفسه يعمل على SQLite وMySQL وPostgreSQL:
+
+```js
+// database/migrations/2026_10_29_120000_create_posts_table.js
+module.exports = {
+  up(schema) {
+    schema.create('posts', (table) => {
+      table.id()
+      table.foreignId('author_id').constrained().cascadeOnDelete()
+      table.string('title', 200).unique()
+      table.text('body').nullable()
+      table.boolean('published').default(false)
+      table.json('meta').nullable()
+      table.timestamps()
+    })
+  },
+  down(schema) {
+    schema.dropIfExists('posts')
+  },
+}
+```
+
+أنواع الأعمدة: `id` و`string` و`text` و`integer` و`bigInteger` و`decimal` و`float` و`boolean` و`date` و`dateTime` و`timestamp` و`timestamps` و`json` و`foreignId`. وملفات `.sql` العادية في `database/migrations` تعمل أيضًا (تُنفَّذ مرة لكل ملف بترتيب الأسماء).
+
+البذرة تملأ بيانات البداية:
+
+```js
+// database/seeders/DatabaseSeeder.js
+const { Seeder } = require('kreftjs/server')
+const Post = require('../../app/Models/Post')
+
+class DatabaseSeeder extends Seeder {
+  async run() {
+    await Post.create({ title: 'مرحبًا', author_id: 1 })
+    await this.call(require('./CommentSeeder'))
+  }
+}
+
+module.exports = DatabaseSeeder
+```
+
+المصانع تصنع بيانات وهمية للبذور والاختبارات:
+
+```js
+await User.factory().count(10).has(Post.factory().count(3), 'posts').create()
+```
+
+### الأوامر
+
+| الأمر | ماذا يفعل |
+|---|---|
+| `kreft migrate` | ينفّذ الترحيلات الجديدة (`kreft dev` يفعل ذلك وحده). |
+| `kreft migrate:rollback` | يتراجع عن آخر دفعة (`--step 2` لآخر اثنتين). |
+| `kreft migrate:fresh --seed` | يحذف كل الجداول ثم يرحّل من جديد ثم يبذر. |
+| `kreft migrate:status` | أي الترحيلات نُفّذت. |
+| `kreft db:seed` | ينفّذ `DatabaseSeeder` (`--class PostSeeder` لغيره). |
+| `kreft make:model Post -mfsc` | نموذج مع ترحيل (`-m`) ومصنع (`-f`) وبذرة (`-s`) ومتحكم (`-c`) وصفحة (`-p`) ومسار (`-r`). |
+| `kreft make:migration create_posts_table` | `add_x_to_posts_table` يصنع `schema.table`. |
+| `kreft make:seeder` و`kreft make:middleware` | الملفات في أماكنها الصحيحة. |
+
+> **ملاحظة:** `migrate:fresh` و`db:wipe` يدمّران البيانات. هما لقواعد التطوير فقط.
+
+## تمارين
+
+1. أنشئ مشروعًا بـ `--db sqlite`، ثم `kreft make:model Product -mfsc` وعدّل الترحيل بإضافة `price` و`stock`.
+2. أضف مسار `GET /api/products/low-stock` يعيد المنتجات التي مخزونها أقل من 5 باستعمال scope.
+3. اكتب بذرة تنشئ 50 منتجًا بالمصنع، وشغّل `kreft migrate:fresh --seed`.

package/book/ar/07-auth-and-security.md

@@ -0,0 +1,157 @@
+# الفصل السابع: المصادقة والوسطاء والأمان
+
+## صفحات الدخول الجاهزة
+
+المشاريع الجديدة (بلا `--no-auth`) تأتي بكل شاشات الدخول والواجهة الخلفية التي وراءها:
+
+| الصفحة | العنوان | ماذا تفعل |
+|---|---|---|
+| `pages/auth/Login.kreft` | `/login` | الدخول بالبريد وكلمة المرور. |
+| `pages/auth/Register.kreft` | `/register` | إنشاء حساب مع بريد لتأكيد العنوان. |
+| `pages/auth/ForgotPassword.kreft` | `/forgot-password` | يرسل رابطًا لاختيار كلمة مرور جديدة. |
+| `pages/auth/ResetPassword.kreft` | `/reset-password/:token` | الرابط القادم في ذلك البريد. |
+| `pages/auth/VerifyEmail.kreft` | `/verify-email` | "تحقق من بريدك"، ورابطه يفتح `/verify-email/:id/:hash`. |
+| `pages/auth/ConfirmPassword.kreft` | `/confirm-password` | أعد كتابة كلمة المرور قبل أمر خطير. |
+| `pages/Dashboard.kreft` و`pages/Profile.kreft` | `/dashboard` و`/profile` | أول صفحة بعد الدخول؛ إعدادات الحساب. |
+
+## كيف يعمل الدخول
+
+- الدخول يضع رمزًا في **كوكي HttpOnly**. سكربتات الصفحة لا تقرؤه، فلا يسرقه سكربت محقون في الصفحة. وفي قاعدة البيانات يُخزَّن تجزئة الرمز فقط.
+- كل تغيير (POST وPUT وPATCH وDELETE) يحتاج ترويسة `X-XSRF-TOKEN` مطابقة لكوكي `XSRF-TOKEN`. و`Kreftjs.api` يفعل ذلك عنك.
+- أي سكربت أو تطبيق يرسل `device_name` عند الدخول يحصل على **رمز API** (`Authorization: Bearer 5|…`) بدل الكوكي.
+- كلمات المرور تُجزَّأ بـ scrypt. روابط الاستعادة تنتهي بعد 60 دقيقة وتُخرج المستخدم من كل مكان.
+- معرّف الجلسة يتغير عند كل دخول، فلا يمكن زرع جلسة في متصفح مسبقًا.
+
+على الخادم:
+
+```js
+Route.middleware(['auth', 'verified']).group(() => {
+  Route.get('/orders', [OrderController, 'index'])               // req.user هو المستخدم
+})
+
+Route.delete('/account', /* … */).middleware(['auth', 'password.confirm'])   // يطلب كلمة المرور مجددًا (423)
+```
+
+مساعدات تستعملها في أي مكان بالواجهة الخلفية:
+
+```js
+const { Hash, Str, Url, Mail, Crypt } = require('kreftjs/server')
+
+Hash.make('secret')                      // خزّن هذه، لا كلمة المرور أبدًا
+Hash.check('secret', user.password)      // true أو false
+Str.random(40)                           // رمز عشوائي
+Url.signed('/verify-email/5/abc', 60)    // رابط يعمل 60 دقيقة دون تغيير
+await Mail.send({ to, subject, text })   // يُطبع في الطرفية حتى تضبط MAIL_URL
+```
+
+## حمايات في مسارات الدخول
+
+- الزوار لهم `throttle:6,1`: ست محاولات في الدقيقة لكل عنوان.
+- كل **حساب** يُقفَل أيضًا بعد `LOGIN_MAX_FAILURES` (10) كلمات مرور خاطئة في `LOGIN_WINDOW_SECONDS` (15 دقيقة)، أيًّا كان عنوان المحاولات. بعدها حتى الكلمة الصحيحة تعطي `429` حتى تنتهي النافذة.
+- رموز المصادقة الثنائية تُعدّ لكل حساب أيضًا: `TWO_FACTOR_MAX_FAILURES` (8) رمزًا خاطئًا يقفل الحساب، وبدء دخول جديد لا يصفّر العدّ.
+- "نسيت كلمة المرور؟" تعطي الجواب نفسه سواء كان للعنوان حساب أو لا.
+- تغيير البريد يحتاج تأكيد كلمة المرور في آخر 3 ساعات (الجواب `423`)، لأن العنوان هو ما تثق به استعادة كلمة المرور.
+
+## المصادقة الثنائية والأجهزة ورموز API
+
+- **المصادقة الثنائية:** رموز تطبيق المصادقة (TOTP) ورموز استرداد. كل رمز استرداد يعمل مرة واحدة.
+- **الأجهزة:** `/profile` يعرض المتصفحات المسجّلة، ويمكن إخراج أي منها.
+- **رموز API:** تُنشأ في `/profile` بالصلاحيات `read` و`create` و`update` و`delete`. الرمز لا يستعمل إلا طرق HTTP التي تسمح بها صلاحياته، على **كل** مسار (`GET` تحتاج `read`، و`POST` تحتاج `create`، و`PUT`/`PATCH` تحتاج `update`، و`DELETE` تحتاج `delete`). جلسات المتصفح ورموز `*` فقط تدير الرموز وكلمة المرور والحساب.
+
+### المديرون
+
+المدير مستخدم عموده `is_admin` صحيح. المستخدم التجريبي مدير؛ وامنح غيره الصلاحية من صفحة المستخدمين أو بـ `kreft make:admin you@example.com`. واستعمل `Route.middleware(['auth', 'admin'])` لمسارات المديرين.
+
+## الوسطاء (Middleware)
+
+الوسيط يعمل قبل المتحكم، ويمكنه إيقاف الطلب أو تغيير الجواب:
+
+```js
+// app/Http/Middleware/EnsureIsAdmin.js     ('ensure-is-admin' في مسار، أو 'ensure-is-admin:editor')
+const { abort } = require('kreftjs/server')
+
+class EnsureIsAdmin {
+  async handle(req, next, role = 'admin') {
+    if (!req.user || req.user.role !== role) abort(403)
+    const response = await next(req)               // المتحكم يعمل هنا
+    return response.header('X-Checked', 'yes')
+  }
+}
+
+module.exports = EnsureIsAdmin
+```
+
+الاسم في المسار يجد ملفه في `app/Http/Middleware`: `'auth'` هو `Authenticate.js`، و`'ensure-is-admin'` هو `EnsureIsAdmin.js`.
+
+### الوسطاء المدمجة
+
+| الوسيط | ماذا يفعل |
+|---|---|
+| `throttle:60,1` | تحديد المعدل: 60 طلبًا في الدقيقة لكل زائر ومسار، ثم `429`. |
+| `csrf` | يفحص رمز CSRF على POST وPUT وPATCH وDELETE (`419` عند الخطأ). |
+| `can:ability,model` | فحوص السياسات عبر `Gate.authorize()`. |
+| `auth` و`guest` و`verified` و`password.confirm` | مجموعة الدخول من `app/Http/Middleware`. |
+
+ولكل المسارات اذكر الوسطاء في `app/Http/Kernel.js`:
+
+```js
+module.exports = {
+  middleware: ['throttle:120,1'],
+}
+```
+
+استثنِ مسارًا بـ `.withoutMiddleware('csrf')`، أو `new VerifyCsrfToken({ except: ['webhooks/*'] })`.
+
+## السياسات (Policies) والتفويض
+
+```js
+// app/Policies/PostPolicy.js
+class PostPolicy {
+  update(user, post) { return user.id === post.user_id }
+  delete(user, post) { return user.is_admin || user.id === post.user_id }
+}
+module.exports = PostPolicy
+```
+
+```js
+// في متحكم
+async update(req, id) {
+  const post = await Post.findOrFail(id)
+  await req.authorize('update', post)        // 403 إن رفضت السياسة
+  await post.update(await UpdatePostRequest.validate(req))
+  return post
+}
+```
+
+وللتوليد: `kreft make:policy PostPolicy`. وكتابة `can:update,post` في الوسيط تفعل الشيء نفسه على مستوى المسار.
+
+## قائمة فحص قبل الإنتاج
+
+| الفحص | لماذا |
+|---|---|
+| `NODE_ENV=production` و`APP_ENV=production` | يطفئ صفحات التصحيح ويفعّل HSTS وتحويل https ويجعل أخطاء الأمان قاتلة. |
+| `APP_DEBUG=false` | لا تُظهر آثار المكدّس أو الشيفرة للزوار أبدًا. |
+| `APP_KEY` بمفتاح من 32 بايت (`kreft key:generate`) | في الإنتاج يرفض التطبيق البدء بمفتاح أقل من 16 بايت. |
+| `APP_URL=https://your.site` | تُستعمل لروابط البريد وتحويل https والكوكيز الآمنة. |
+| `TRUSTED_PROXIES` إن استعملت وسيطًا | وإلا يشترك كل الزوار في عنوان الوسيط وحدود المعدل. |
+| `DATABASE_URL` حقيقي وخطة نسخ احتياطي | SQLite تكفي للصغير؛ استعمل MySQL أو PostgreSQL لعدة خوادم. |
+| `CACHE_STORE=redis` أو `database`، و`QUEUE_CONNECTION=redis` أو `database` | `memory` لكل عملية على حدة. وأقفال الحسابات في الذاكرة المؤقتة. |
+| `MAIL_URL` مضبوط | وإلا تُطبع الرسائل في الطرفية فقط. |
+| `MCP_TOKEN` مضبوط، أو MCP مطفأ | نقطة MCP معطلة في الإنتاج بدونه. |
+| لا مستخدم تجريبي | لا تشغّل `--seed` على الإنتاج؛ واحذف `test@example.com`. |
+| HTTPS أمام التطبيق مع `FORCE_HTTPS=true` | الكوكيز `Secure` في الإنتاج. |
+| `npm audit` و`kreft update` | أصلح الثغرات المعروفة قبل الإصدار. |
+
+> **ملاحظة:** Kreft لا يغني عن مراجعة أمنية. للأنظمة الحساسة، ادعُ متخصصًا لمراجعة التطبيق والبنية والاعتماديات.
+
+## أدوات الحماية في الواجهة
+
+- القيم تُهرَّب دائمًا في القوالب. و`k-html` يُنظَّف من السكربتات لكن اربط HTML تثق به فقط.
+- التطبيق المبني (`kreft build`) لا يستعمل `eval` ولا `new Function`، فتعمل معه سياسة أمان المحتوى (CSP) الصارمة.
+- `Kreftjs.env` يحمل المتغيرات التي تبدأ بـ `PUBLIC_` فقط؛ لا تضع سرًّا في واحد منها.
+
+## تمارين
+
+1. أنشئ سياسة `ProductPolicy` تسمح للمدير فقط بالحذف، واختبرها برمز API محدود الصلاحيات.
+2. أضف وسيطًا `ensure-subscribed` يجيب `402` لمن ليس مشتركًا.
+3. فعّل المصادقة الثنائية لحسابك من `/profile` واحتفظ برموز الاسترداد.