> ## Documentation Index > Fetch the complete documentation index at: https://shinydapps-bd9fa40b.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # تدفقات النظام > مخططات مرئية لكل تدفق في منصة l402-kit — الدفع، والمصادقة، والاشتراك، والبنية التحتية. توثّق هذه الصفحة كل تدفق رئيسي في منصة l402-kit على شكل مخططات تسلسلية ومخططات انسيابية. يقترن كل قسم بمرئي وشرح موجز لما يحدث ولماذا يعمل بهذه الطريقة. ابدأ بالتدفق 1 (L402 الأساسي) لفهم الأساس التشفيري، ثم اقرأ التدفقات ذات الصلة بتكاملك. *** ## 1. تدفق دفع L402 الأساسي دورة الطلب الجوهرية. لا حسابات، لا كلمات مرور — مجرد إيصال تشفيري. عندما يصل عميل لأول مرة إلى نقطة نهاية محمية، يتلقى استجابة HTTP 402 تحتوي على شيئين: فاتورة BOLT11 عبر Lightning Network وmacaroon. يدفع العميل الفاتورة عبر Lightning Network (عادةً في أقل من ثانية)، ويتلقى preimage بحجم 32 بايت كدليل، ثم يُعيد الطلب مع `Authorization: L402 :`. يتحقق الخادم من الرمز محلياً باستخدام `SHA256(preimage) === macaroon.hash` — لا استدعاء لقاعدة البيانات، لا رحلة ذهاب وعودة عبر الشبكة، زمن استجابة أقل من ميلي ثانية. بمجرد التحقق، يكون الرمز صالحاً حتى انتهاء صلاحيته. تُعيد الطلبات اللاحقة استخدام نفس الترويسة. ```mermaid theme={null} sequenceDiagram participant C as Client / AI Agent participant S as Your API Server participant L as Lightning Network participant B as Blink (provider) C->>S: GET /api/data (no token) S-->>C: 402 Payment Required
WWW-Authenticate: L402 macaroon="...", invoice="lnbc..." Note over C,L: Client pays the Lightning invoice C->>L: pay(invoice) L-->>C: preimage (32-byte proof of payment) C->>S: GET /api/data
Authorization: L402 : Note over S: SHA256(preimage) === macaroon.hash?
Verified in <1ms locally. No DB call. S-->>C: 200 OK + data ``` **الخصائص الرئيسية:** * التحقق محلي بالكامل — لا استدعاء شبكي، لا بحث في قاعدة البيانات * `preimage` = دليل تشفيري على الدفع (إيصال Lightning) * `macaroon` = JSON بترميز base64 `{hash, exp}` موقّع بـ SHA-256 *** ## 2. تشريح الرمز تحمل ترويسة `Authorization` مكوّنَين مفصولَين بنقطتين. **macaroon** هو كائن JSON مُشفَّر بـ base64 `{hash, exp}` — يُخبر الخادم بهاش الدفع المتوقع ووقت انتهاء صلاحية الرمز. أما **preimage** فهو السر بحجم 32 بايت الذي أعادته Lightning Network إلى الدافع. معاً يُشكّلان بيانات اعتماد غير قابلة للتزوير ومكتفية بذاتها يمكن لأي خادم التحقق منها دون اتصال. ```mermaid theme={null} flowchart LR T["Authorization: L402 <macaroon>:<preimage>"] T --> M["macaroon\nbase64({ hash, exp })\nSigned by SHA-256"] T --> P["preimage\n32-byte hex secret\nSHA256(preimage) = hash"] M --> V["Server verifies:\nSHA256(preimage) === hash\nexp > now()"] ``` *** ## 3. الوضع المُدار — تدفق تقسيم الرسوم عند استخدام `ManagedProvider`، تُنشئ l402kit.com الفاتورة، وتستقبل الدفع، وتُحوّل 99.7% إلى عنوان Lightning الخاص بك تلقائياً. تغطي رسوم المنصة البالغة 0.3% توجيه Lightning وبنية تحتية API. لا تلمس محفظتك Cloudflare Worker أبداً — فالتقسيم عبارة عن دفع Lightning من جانب الخادم يُطلَق بعد التحقق من طلب العميل، باستخدام عنوان Lightning الخاص بك لإنشاء فاتورة BOLT11 جديدة في الوقت الفعلي. ```mermaid theme={null} sequenceDiagram participant C as Client participant V as Cloudflare Worker
/api/invoice participant B as Blink API
(ShinyDapps wallet) participant S as Supabase participant O as Owner wallet
(you@yourdomain.com) C->>V: POST /api/invoice
{priceSats, ownerAddress} V->>B: lnInvoiceCreate(priceSats) B-->>V: {paymentRequest, paymentHash} V-->>C: 402 + invoice Note over C,B: Client pays invoice C->>B: pay(invoice) B-->>C: preimage C->>V: GET /api/data + L402 token V->>S: INSERT payments
{payment_hash, endpoint, amount_sats} V->>V: POST /api/split
(fire-and-forget) V->>B: sendPayment(owner, 99.7%) B-->>O: ⚡ sats received V-->>C: 200 OK + data ``` *** ## 4. تدفق اشتراك Pro تتبع اشتراكات Pro نمطاً مشابهاً لـ L402 لكنها تُضيف حالة دائمة. يدفع العميل فاتورة لمرة واحدة ويحصل على سجل اشتراك مدته 30 يوماً في Supabase. يصل تأكيد الدفع إما عبر Blink webhook (المسار السريع، \~ثانيتان) أو عبر الاستطلاع (بديل للمحافظ التي لا تُطلق webhooks). تتحقق استدعاءات `/api/pro-check` اللاحقة من طابع `expires_at` الزمني دون دفع آخر. ```mermaid theme={null} sequenceDiagram participant U as User (VS Code) participant V as Cloudflare Worker participant B as Blink API participant S as Supabase participant W as Blink Webhook U->>V: POST /api/pro-subscribe
{lightningAddress, tier} V->>B: lnInvoiceCreate(amountSats) B-->>V: {paymentRequest, paymentHash} V->>S: INSERT pro_access
{address, payment_hash, expires_at: null} V-->>U: {paymentRequest, paymentHash} Note over U,B: User pays invoice in their wallet U->>B: pay(invoice) alt Webhook path (fast) B->>W: POST /api/blink-webhook
{type: "transaction.ln.invoice.paid"} W->>S: PATCH pro_access
SET expires_at = now + 30d else Poll path (fallback) U->>V: GET /api/pro-poll?paymentHash=... V->>B: lnInvoice(paymentHash) → status V->>S: PATCH pro_access SET expires_at V-->>U: {active: true, expires_at} end U->>V: GET /api/pro-check?address=... V->>S: SELECT expires_at WHERE address=? V-->>U: {active: true, tier: "pro"} ``` *** ## 5. LNURL-auth — إثبات ملكية المحفظة (حذف البيانات) يُثبت أنك تمتلك محفظة Lightning دون كلمة مرور. مطلوب قبل حذف بيانات الحساب. ```mermaid theme={null} sequenceDiagram participant U as User (VS Code) participant V as Cloudflare
/api/lnurl-auth participant W as Lightning Wallet
(Phoenix, Blink…) participant S as Supabase
lnurl_challenges participant D as Cloudflare
/api/delete-data U->>V: GET /api/lnurl-auth
?lightningAddress=you@yourdomain.com V->>V: k1 = randomBytes(32) V->>S: INSERT {k1, lightning_address, expires_at: +5min} V-->>U: {k1, lnurl} — show as QR code Note over U,W: User scans QR with Lightning wallet W->>W: Sign k1 with secp256k1
key derived for this domain W->>V: GET /api/lnurl-auth
?tag=login&k1=…&sig=…&key=… V->>V: secp256k1.verify(sig, k1, pubkey) V->>V: token = randomBytes(32), TTL 10min V->>S: PATCH {verified: true, pubkey, token} V-->>W: {status: "OK"} loop Poll every 2s U->>V: GET /api/lnurl-auth?poll= V->>S: SELECT verified, token WHERE k1=? V-->>U: {verified: true, token: "abc…"} end U->>D: POST /api/delete-data
{lightningAddress, token} D->>S: SELECT WHERE token=? → verified? expired? D->>S: PATCH token = null (revoke — single use) D->>S: DELETE payments WHERE owner_address=? D->>S: DELETE pro_access WHERE address=? D-->>U: {deleted: {payments: N, proAccess: true}} ``` *** ## 6. تدفق تسجيل الدخول إلى لوحة التحكم عبر LNURL-auth مصادقة لوحة التحكم مقتصرة على المالك — DASHBOARD\_SECRET مخزّن في أسرار Cloudflare Workers. ```mermaid theme={null} sequenceDiagram participant O as Owner browser participant V as Cloudflare
/api/lnurl-auth participant W as Owner Lightning Wallet participant S as Supabase
lnurl_challenges participant D as Cloudflare
/api/stats O->>V: GET /api/lnurl-auth?dashboard=1 V->>V: k1 = randomBytes(32) V->>S: INSERT {k1, lightning_address: "__dashboard__", expires_at: +5min} V-->>O: {k1, lnurl} — show QR code Note over O,W: Owner scans QR with their Lightning wallet W->>W: Sign k1 with secp256k1 key W->>V: GET /api/lnurl-auth
?tag=login&k1=…&sig=…&key=… V->>V: key === OWNER_PUBKEY? ✓ V->>V: secp256k1.verify(sig, k1, key) V->>V: token = randomBytes(32), TTL 24h V->>S: PATCH {verified: true, pubkey, token, token_expires_at} V-->>W: {status: "OK"} loop Poll every 2s O->>V: GET /api/lnurl-auth?poll= V->>S: SELECT verified, token WHERE k1=? V-->>O: {verified: true, token: "abc…"} end O->>D: GET /api/stats
x-lnurl-token: D->>S: SELECT verified, pubkey, token_expires_at WHERE token=? D->>D: pubkey === OWNER_PUBKEY? ✓ not expired? ✓ D-->>O: {totalPayments, totalSats, byDay, trend, recent…} ``` *** ## 7. نظرة عامة على البنية التحتية ```mermaid theme={null} flowchart TB subgraph CF["Cloudflare DNS (l402kit.com)"] DNS["l402kit.com\nCNAME → l402kit-pages.pages.dev"] end subgraph VCL["Cloudflare (Workers + Pages)"] LAND["Landing Page\nbackend/index.html"] API["Backend API\n/api/invoice → Edge Function\n/api/delete-data\n/api/lnurl-auth\n/api/pro-subscribe\n/api/stats (LNURL-auth)"] HOOK["Webhooks\n/api/blink-webhook"] end subgraph SB["Supabase (PostgreSQL + Edge Functions)"] PAY["payments\npayment_hash · amount_sats\nowner_address · endpoint"] PRO["pro_access\naddress · tier\nexpires_at · payment_hash"] LNURL["lnurl_challenges\nk1 · verified · token\ntoken_expires_at · pubkey"] EF["Edge Function: create-invoice\nBLINK_API_KEY (Supabase Secret)\nBLINK_WALLET_ID (Supabase Secret)"] end subgraph EXT["External Services"] BLINK["Blink Lightning\napi.blink.sv"] end CF --> VCL API --> SB HOOK --> SB EF --> BLINK BLINK --> HOOK ``` *** ## 8. أمان SHA-256 Preimage لماذا نخزّن `SHA256(preimage)` بدلاً من preimage الخام: ```mermaid theme={null} flowchart LR subgraph Lightning["Lightning Network (public)"] INV["BOLT11 Invoice\ncontains payment_hash = SHA256(preimage)"] end subgraph Client["Client (private)"] PRE["preimage\n32-byte secret\nproof of payment"] end subgraph DB["Supabase payments table"] STORED["payment_hash\n= SHA256(preimage)\nsafe to store"] end PRE -->|"SHA256()"| STORED INV -->|"already public"| STORED PRE -.->|"❌ never store raw"| DB style PRE fill:#ff4444,color:#fff style STORED fill:#22c55e,color:#fff ``` **لماذا هو آمن:** `payment_hash` مُضمَّن بالفعل في كل فاتورة BOLT11 — فهو عام بطبيعته. فقط `preimage` هو السر. يمنحك تخزين الهاش حماية من إعادة التشغيل دون أي تعرض إضافي.