وثائق كتاب Sibuna 1.0.0-beta.3
اللغة: العربية
English简体中文한국어日本語EspañolDeutschहिन्दीالعربية
في هذه الصفحة

الجزء الرابع: بروتوكول Sibuna

نحدد بروتوكول النقل كما هو منفَّذ: دورة الصفحة الوسيطة، وسجل التحدي عديم الحالة، وتنسيقي الحل، وترتيب التحقق، وفرض الاستخدام لمرة واحدة، وملف تعريف ارتباط الجلسة.

دورة التحدي

حلقة من ثماني خطوات: تنقل المتصفح، ثم الصفحة الوسيطة (HTTP 200)، ثم GET /__sibuna/challenge.json?need=، ثم المعرّف عديم الحالة (الحمولة + الوسم)، ثم الحل في Web Worker بمُبرهِن WASM أو JS، ثم POST /__sibuna/verify مع القيمة المؤقتة أو الإثبات، ثم التحقق وتسجيل الحل في مجموعة الحلول المُنفَقة وإصدار رمز MAC، ثم Set-Cookie وإعادة التحميل، والعودة إلى التنقل بجلسة.
الشكل 5 دورة التحدي. تجري الخطوات التي على اليسار في المتصفح، والتي على اليمين في Sibuna.
  1. يصل تنقل بلا جلسة صالحة إلى محرك السياسة، فيُصنَّف CHALLENGE. ولأن الطلب يقبل text/html، يجيب البرنامج الخدمي بالحالة 200 مع الصفحة الوسيطة والترويسة X-Sibuna-Status: CHALLENGE؛ أما عميل API الذي لا يقبل HTML فيتلقى 401 مع جسم JSON يحمل عنوان challenge جاهزًا للجلب. وفي الحالتين تحمل الاستجابة تذكرة متطلبات: التحدي الذي يفرضه هذا القرار (الخوارزمية، وبتات العمل، وعدد عمليات الفتح) وتجزئة القاعدة، مختومة لهذا العميل بوسم BLAKE3 ذي مفتاح بمفتاحها المشتق الخاص، وصالحة مدة عمر تحدٍّ واحد.

  2. تجلب الصفحة الوسيطة GET /__sibuna/challenge.json?path=<original URL>&need=<ticket>. فإذا كانت التذكرة صالحة حددت التحدي: فالعمل يحدده القرار الذي طلبه، ولا يُعاد حسابه من عنوان URL يبلغ عنه العميل ومن ترويسات الجلب نفسه، وهي تختلف عن ترويسات التنقل (Accept، وSec-Fetch-*). ومن دون تذكرة صالحة (عميل API يتجاهل العنوان، أو صفحة بقيت مفتوحة بعد انقضاء العمر) يقيّم الخادم عنوان URL المُبلَّغ عنه، مقسومًا إلى مسار واستعلام بالدالة نفسها التي تقرأ سطر الطلب، بعد وضع المسار في الصيغة القياسية التي يستخدمها القبول (SID 0009)؛ ويُرفض العنوان الأطول من 8 KiB بالحالة 414 ولا يُقتطع أبدًا، ويُرفض المسار الذي ليست له صيغة قياسية بالحالة 400. والتذكرة استرشادية: يظل القبول يفحص مستوى عمل الجلسة، فلا تكلف التذكرة المعادة أو المزورة حاملها إلا عملًا.

  3. الاستجابة هي سجل التحدي:

    {"id":"AQEND...70 chars","algorithm":"posw","difficulty":13,"challenges":16,"expires_at":1757241234}
    

    بالنسبة إلى hashcash، يمثل difficulty عدد البتات، ويساوي challenges القيمة 0.

  4. يحله Web Worker بوحدة WebAssembly، أو بمُبرهِن JavaScript إذا لم تتوفر WebAssembly (الجزء السابع)، ويرسل إما

    {"challenge_id":"...","nonce":"90766"}
    

    أو

    {"challenge_id":"...","proof":"<base64url, 32(1 + t(n+1)) bytes>"}
    

    إلى POST /__sibuna/verify.

  5. عند النجاح يجيب الخادم بـ 200 {"status":"ok"} مع ترويسة Set-Cookie، وتعيد الصفحة تحميل موقعها الأصلي. يحمل كل طلب لاحق ملف تعريف الارتباط، ويُقبل قبل تقييم السياسة.

سجل التحدي عديم الحالة

pub fn create_challenge_with_spec(
    &self,
    client_ip: &[u8],
    user_agent: &[u8],
    now: u64,
    spec: ChallengeSpec,
    rule_hash: u64,
) -> Challenge {
    self.adaptive.observe(now.saturating_mul(1000));
    let effective = ChallengeSpec {
        difficulty: spec.difficulty.saturating_add(self.adaptive.bump()),
        ..spec
    };
    let fingerprint = self.fingerprint(client_ip, user_agent);
    let difficulty = effective.parameter();
    let challenges = match effective.algorithm {
        Algorithm::Hashcash => 0,
        Algorithm::Posw => effective.posw_challenges,
    };

    let mut payload = [0u8; ID_PAYLOAD_LEN];
    payload[0] = ID_VERSION;
    payload[1] = effective.algorithm.to_byte();
    payload[2] = difficulty;
    payload[3] = challenges;
    payload[4..12].copy_from_slice(&now.to_le_bytes());
    payload[12..20].copy_from_slice(&fingerprint.to_le_bytes());
    payload[20..28].copy_from_slice(&self.next_nonce(now, fingerprint).to_le_bytes());
    payload[28..36].copy_from_slice(&rule_hash.to_le_bytes());
    let mut raw = [0u8; ID_RAW_LEN];
    raw[..ID_PAYLOAD_LEN].copy_from_slice(&payload);
    raw[ID_PAYLOAD_LEN..].copy_from_slice(&self.challenge_tag(&payload));

    Challenge {
        id: encoded::encode(&raw),
        algorithm: effective.algorithm,
        difficulty,
        challenges,
        expires_at: now.saturating_add(u64::from(self.challenge_ttl)),
    }
}

المعرّف من النوع Encoded<70>: يُحفظ النص في مصفوفة بطوله تمامًا، فلا يخصص إصدار التحدي أي ذاكرة. وتحوّل ChallengeSpec::parameter بتات العمل إلى وحدة المستوى نفسه: بتات Hashcash (64 على الأكثر)، أو عمق PoSW (difficulty - 3، محصورًا بين 4 و24).

تستحق ثلاثة تفاصيل الانتباه:

  • الصعوبة التكيفية. يحتفظ المنسق بمتوسط متحرك مرجح أسيًا لمعدل إصدار التحديات في ثلاث قيم ذرية. فوق خط أساس قدره 50 تحديًا في الثانية، تضيف كل مضاعفة للمعدل بت عمل واحدًا، بحد أقصى ستة. يدفع الإغراق تكلفة تزداد أسيًا، بينما تحتفظ الحركة الهادئة بالتكلفة الأساسية.
  • القيمة المؤقتة خرج دالة PRF، بمفتاح التحدي على عداد والساعة والبصمة. وهي فريدة (بفضل العداد) وغير قابلة للتنبؤ (بفضل المفتاح)، فلا يستطيع الخصم حساب حلول مسبقًا لمعرفات لم تُصدر له، ولا يستدعي المسار الساخن نظام التشغيل أبدًا للحصول على العشوائية.
  • الوسم يغطي الصعوبة. لا يستطيع العميل خفض الصعوبة بتعديل السجل: فسيفشل الوسم قبل فحص أي إثبات.

ترتيب التحقق والاستخدام الواحد

pub fn verify_and_mint(
    &self,
    challenge_id: &[u8],
    solution: Solution<'_>,
    client_ip: &[u8],
    user_agent: &[u8],
    now: u64,
) -> Result<Verified, VerifyError> {
    let record = self.decode(challenge_id)?;
    let expires_at = record.issued_at.saturating_add(u64::from(self.challenge_ttl));
    if now > expires_at || record.issued_at > now.saturating_add(CLOCK_SKEW_SECONDS) {
        return Err(VerifyError::ChallengeExpired);
    }
    if record.fingerprint != self.fingerprint(client_ip, user_agent) {
        return Err(VerifyError::FingerprintMismatch);
    }
    check_solution(challenge_id, &record, solution)?;
    self.spent.mark_spent(&record.tag, expires_at, now).map_err(|error| match error {
        SpendError::DoubleSpend => VerifyError::DoubleSpendAttempt,
        SpendError::Full => VerifyError::StoreFull,
    })?;
    let work = WorkLevel {
        algorithm: record.algorithm.to_byte(),
        bits: record.algorithm.work_bits(record.difficulty),
    };
    Ok(Verified {
        token: self.mint_token(now, record.rule_hash, record.fingerprint, work),
        algorithm: record.algorithm,
        difficulty: record.difficulty,
        challenges: record.challenges,
        ttl_seconds: self.token_ttl,
    })
}

الترتيب مقصود. فالوسم والعمر والارتباط فحوص ثابتة الزمن ترفض المدخلات العبثية قبل أي تجزئة. ويجب ألا يستهلك الإثبات الخاطئ التحدي، لذا لا يُكتب في مجموعة الحلول المُنفَقة إلا بعد نجاح check_solution. وإذا تحقق خيطان من الحل الصالح نفسه تسابقا على mark_spent؛ فيرتّبهما قفل الشريحة، ويفوز واحد منهما بالضبط، ويتلقى الآخر VerifyError::DoubleSpendAttempt. ويرفض الشرط issued_at > now + 60 (قيمة CLOCK_SKEW_SECONDS هي 60) السجلات الصادرة عن عقدة تتقدم ساعتها بأكثر من دقيقة، وإلا لأطالت هذه السجلات عمر التحدي.

تظهر الأخطاء للعميل بالحالة 400 مع تشخيص بأسلوب Elm (الجزء العاشر): يتحول كل VerifyError إلى sibuna_core::errors::ErrorKind، ويكون شرحه جسم الاستجابة. وتتحقق اختبارات الطرف إلى الطرف من وجود DOUBLE SPEND وFINGERPRINT MISMATCH وWRONG SOLUTION TYPE وMALFORMED CHALLENGE في جسم الاستجابة.